@trueraft/sdk

Typed TypeScript client for the Trueraft verification + reverse-KYC API. Covers the verify engine (8 doc types), trust scoring, badge lookup, fraud feed, MSME / RERA / litigation / pay-verify, and includes a webhook signature verifier.

Install

npm install @trueraft/sdk

Requires Node ≥ 18 (uses native fetch and AbortSignal.timeout).

Quickstart

import { Trueraft } from "@trueraft/sdk";

const tr = new Trueraft({ apiKey: process.env.TRUERAFT_API_KEY! });

// Verify a single document — RC, DL, PAN, GSTIN, AADHAAR, BANK, FASTAG, CHASSIS
const rc = await tr.verify({ doc_type: "RC", doc_number: "MH12AB1234" });
console.log(rc.data?.owner_name);

What's in here

| Method | Endpoint | Purpose | |---|---|---| | verify() | POST /functions/v1/verify | Single-document verification | | verifyMany() | (parallel verify) | Concurrent batch with rate-limit-safe cap | | driverScore() | POST /functions/v1/driver-score | RC + DL → 0–100 score | | vehicleScore() | POST /functions/v1/trust-score | RC → 0–100 score | | badge() | GET /api/v1/badge | Trueraft Verified badge lookup | | fraudFeed() | GET /api/v1/fraud-feed | Paginated fraud-signal stream (enterprise) | | payVerify() | POST /api/v1/pay-verify | UPI / phone / PAN trust score | | msmeScore() | POST /api/v1/msme-score | MSME vendor-fitness score | | reraCheck() | POST /api/v1/rera-check | RERA registration lookup | | litigationCheck() | POST /api/v1/litigation-check | Court records by name + PAN | | health() | GET /functions/v1/health-check | Live provider status | | verifyWebhookSignature() | (helper) | HMAC-SHA256 webhook verification |

Idempotency

Pass idempotency_key to make a verification replay-safe. The same key returns the cached result for 24 hours instead of re-charging credits:

await tr.verify({
  doc_type:        "RC",
  doc_number:      "MH12AB1234",
  idempotency_key: "order-1284",
});

Errors + retries

All API failures throw a TrueraftError:

import { TrueraftError } from "@trueraft/sdk";

try {
  await tr.verify({ doc_type: "RC", doc_number: "INVALID" });
} catch (err) {
  if (err instanceof TrueraftError) {
    console.error(err.status, err.message, err.requestId, err.retryAfter);
  }
}

The SDK automatically retries on 5xx, 429, and network errors — by default 3 attempts with exponential backoff (200 ms → 400 ms → 800 ms). A server-supplied Retry-After header wins over the default schedule. Override:

new Trueraft({ apiKey: "...", retries: 5, retryBackoffMs: 500 });

4xx errors (other than 429) are not retried — those are caller bugs and should fail fast.

Fraud feed (incremental polling)

let cursor = ""; // store between runs

while (true) {
  const page = await tr.fraudFeed({ since: cursor, limit: 1000 });
  for (const row of page.results) {
    // row.entity_hash is HMAC-SHA256 of the entity — compare against your hashed inputs
  }
  if (page.results.length === 0) break;
  cursor = page.next_since;
}

For high-volume consumers, pass format: "ndjson" and stream the body.

Webhook signature verification

Trueraft signs every outbound webhook delivery with HMAC-SHA256 of the raw body. Verify before trusting:

import express from "express";
import { verifyWebhookSignature } from "@trueraft/sdk";

const app = express();
app.post("/webhooks/trueraft", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.header("X-Trueraft-Signature") ?? "";
  if (!verifyWebhookSignature(req.body, sig, process.env.TRUERAFT_WEBHOOK_SECRET!)) {
    return res.status(401).end();
  }
  const event = JSON.parse(req.body.toString());
  // ... handle event
  res.status(204).end();
});

The compare is constant-time — safe against signature-leak timing oracles.

Rate-limit awareness

Pass an onResponse hook to inspect rate-limit headers on every call:

new Trueraft({
  apiKey: "...",
  onResponse: ({ url, status, rateLimit }) => {
    if (rateLimit.remaining !== null && rateLimit.remaining < 10) {
      logger.warn(`Trueraft rate-limit low: ${rateLimit.remaining}/${rateLimit.limit}`);
    }
  },
});

Configuration

new Trueraft({
  apiKey:          "trk_live_…",
  baseUrl:         "https://api.trueraft.com",  // engine endpoints (verify, trust-score)
  webBaseUrl:      "https://trueraft.com",      // web endpoints (badge, fraud-feed, etc.)
  timeoutMs:       30_000,
  fetch:           customFetch,                 // override (e.g., undici, node-fetch polyfill)
  retries:         3,
  retryBackoffMs:  200,
  onResponse:      handler,
});

Versioning

This SDK follows the API versioning policy at https://trueraft.com/docs/versioning. Major SDK version bumps track API major bumps (1:1). Minor bumps may add new methods but never remove them. The current API version is v1.

Support

• Docs: https://trueraft.com/docs
• Issues / bugs: [email protected]
• Security disclosures: [email protected]

License

MIT