isCredible SDK

Official TypeScript SDK for the isCredible fraud detection platform.

Installation

npm install is-credible

Quick Start

import { isCredible, VerificationResult } from 'is-credible';

// Initialize with your API key
isCredible.initialize({
  apiKey: 'your_api_key_here'
});

// Verify a user
async function verifyUser() {
  try {
    const result = await isCredible.verify({
      email: '[email protected]',
      ip: '192.168.1.1',
      deviceId: 'device-fingerprint-123'
    });

    console.log('Verification result:', result);
    // {
    //   requestId: '1625097600000',
    //   timestamp: '2023-07-01T12:00:00.000Z',
    //   overallRecommendation: 'APPROVE' | 'DENY' | 'REVIEW',
    //   overallRiskScore: 25,
    //   scenarioResults: [...],
    //   metadata: {...},
    //   summary: 'Verification passed with a risk score of 25.0...'
    // }

    if (result.overallRecommendation === 'APPROVE') {
      // Process user normally
    } else if (result.overallRecommendation === 'REVIEW') {
      // Flag for manual review
    } else {
      // Deny access
    }
  } catch (error) {
    console.error('Verification failed:', error);
  }
}

verifyUser();

Usage with Express

import express from 'express';
import { isCredible, IsCredibleError } from 'is-credible';

const app = express();
app.use(express.json());

// Initialize isCredible
isCredible.initialize({
  apiKey: process.env.ISCREDIBLE_API_KEY as string
});

// Middleware for user verification
const verifyUserMiddleware = async (req: express.Request, res: express.Response, next: express.NextFunction) => {
  try {
    const verification = await isCredible.verify({
      email: req.body.email,
      ip: req.ip,
      deviceId: req.headers['device-fingerprint'] as string
    });

    // Attach verification result to request
    (req as any).userVerification = verification;

    if (verification.overallRecommendation === 'DENY' &&
      verification.overallRiskScore > 80) {
      return res.status(403).json({
        error: "High risk user detected",
        message: "Please contact support"
      });
    }

    next();
  } catch (error) {
    console.error("Verification error:", error);
    next();
  }
};

app.post('/api/claim-credits', verifyUserMiddleware, (req, res) => {
  // Safe to grant credits, user has been verified
  const { overallRecommendation, overallRiskScore } = (req as any).userVerification;

  if (overallRecommendation === 'APPROVE') {
    // Full credits
    return res.json({ credits: 100, message: "Full credits granted" });
  } else if (overallRecommendation === 'REVIEW') {
    // Limited credits until further review
    return res.json({ credits: 25, message: "Limited credits granted pending review" });
  }

  // Should not reach here due to middleware, but just in case
  return res.status(403).json({ error: "Unable to grant credits" });
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

API Reference

Initialize

import { isCredible } from 'is-credible';

isCredible.initialize({
  apiKey: 'your_api_key',
  baseUrl: 'https://custom-api-url.com' // Optional
});

Verify

import { isCredible, UserData, VerifyOptions } from 'is-credible';

const userData: UserData = {
  email: '[email protected]',
  ip: '192.168.1.1',
  deviceId: 'device-fingerprint-123',
  // Any additional data fields
  firstName: 'John',
  lastName: 'Doe',
  signupDate: '2023-07-01T12:00:00.000Z'
};

const options: VerifyOptions = {
  scenarioId: 'specific-scenario-id', // Optional
  profileId: 'your-profile-id' // Optional
};

const result = await isCredible.verify(userData, options); 

Direct Client Usage

If you need more control, you can use the client directly:

import { IsCredibleClient } from 'is-credible';

const client = new IsCredibleClient({
  apiKey: 'your_api_key'
});

const result = await client.verify(userData, options); 

Verification Result Structure (TBD)

NOTE: The structure may vary depending on some special rules. Please contact support if it doesn't match for you or should you need any assistance.

interface VerificationResult {
  requestId: string;
  timestamp: string;
  overallRecommendation: string; // 'APPROVE', 'DENY', 'REVIEW', 'ERROR'
  overallRiskScore: number; // 0-100
  scenarioResults: ScenarioResult[];
  metadata: {
    processedScenarios: number;
    dataItems: number;
    executionTimeMs: number;
    userId?: string;
    profileId?: string;
  };
  summary: string;
}

interface ScenarioResult {
  scenarioId: string;
  scenarioName: string;
  valid: boolean;
  riskScore: number;
  recommendation: string;
  matchedRules: number;
  totalRules: number;
  executionTimeMs: number;
  anomalies: string[];
  recommendations: string[];
  summary: string;
  ruleReports: RuleReport[];
}

interface RuleReport {
  ruleId: string;
  title: string;
  passed: boolean;
  score: number;
  executionTimeMs: number;
  details?: any;
}

Error Handling

The SDK throws IsCredibleError with additional properties:

import { isCredible, IsCredibleError } from 'is-credible';

try {
  const result = await isCredible.verify(userData);
} catch (error) {
  if (error instanceof IsCredibleError) {
    console.error(`API Error (${error.status}):`, error.message);
    console.error('Error details:', error.data);
  } else {
    console.error('Unexpected error:', error);
  }
}

TypeScript Support

This SDK is written in TypeScript and provides full type definitions for all functionality.

Need Help?

[email protected]