@simplr-ai/node

Simplr's server-side SDK for Node.js — run fraud/identity checks, score orders, ingest edge logs, and verify webhook signatures, all with your secret key.

This is the backend SDK. For client-side device signals, RUM, and feature-flag evaluation use @simplr-ai/js (browser) or simplr_fraud (Flutter).

Docs: https://simplr-docs-three.vercel.app/sdks/node

Install

npm install @simplr-ai/node

Requires Node 18+ (uses the built-in fetch and crypto).

Quick start

import { Simplr } from "@simplr-ai/node";

const simplr = new Simplr({ apiKey: process.env.SIMPLR_API_KEY! }); // sk_live_… / sk_test_…

const result = await simplr.check({ email: "[email protected]", event_type: "signup" });
if (result.risk_level === "high" || result.risk_level === "critical") {
  // require extra verification
}

baseUrl defaults to https://api.simplr-ai.com; override it for local/dev:

new Simplr({ apiKey: "sk_test_…", baseUrl: "http://localhost:7002" });

Checks

await simplr.check({ phone: "+14155550100", event_type: "login" });
await simplr.checkBulk([{ email: "[email protected]" }, { phone: "+1..." }]); // up to 100

Orders

await simplr.orders.submit({ order_id: "o_1", external_id: "cust_1", amount: 249, currency: "USD" });
await simplr.orders.submitBulk([/* up to 100 orders */]);

Phone intelligence

await simplr.phone.report({ phone: "+14155550100", outcome: "sim_swap_fraud", confidence: 0.9 });
await simplr.phone.intelligence("+14155550100");

Edge devices & logs

await simplr.edge.registerDevice({ device_id: "POS-0042", name: "Front till" });
await simplr.edge.heartbeat("POS-0042", { cpu: 0.34, battery: 0.78 });
await simplr.edge.ingestLogs("POS-0042", [{ category: "transaction", level: "info", message: "sale ok" }]);

Webhooks

Verify the X-Simplr-Signature header against the raw request body (don't re-serialize parsed JSON):

import express from "express";
import { Simplr } from "@simplr-ai/node";

const simplr = new Simplr({ apiKey: process.env.SIMPLR_API_KEY! });
const app = express();

app.post("/hooks/simplr", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.header("X-Simplr-Signature")!;
  try {
    const event = simplr.webhooks.constructEvent(req.body, sig, process.env.SIMPLR_WEBHOOK_SECRET!);
    // event.event, event.data
    res.sendStatus(200);
  } catch {
    res.sendStatus(400); // invalid signature
  }
});

verify(payload, header, secret, { toleranceSec }) returns a boolean; constructEvent(...) returns the parsed event or throws WebhookVerificationError.

Server-side feature flags

Evaluate flags on the backend. Flag config is read with a public key (pk_…), so pass one alongside your secret key; evaluation is local and deterministic (same bucketing as the browser SDK).

const simplr = new Simplr({
  apiKey: process.env.SIMPLR_API_KEY!,       // sk_… for checks/orders/etc.
  publicKey: process.env.SIMPLR_PUBLIC_KEY!, // pk_… for flags
});

await simplr.flags.initialize();
simplr.flags.setUser("user_123");

if (simplr.flags.isEnabled("new-checkout")) {
  // gate a backend code path
}
simplr.flags.isEnabled("beta", { userId: "u1", attributes: { plan: "growth" } });

Targeting a named environment

environment accepts a named environment slug (e.g. "dev", "uat", "prod") as well as the legacy "live"/"test" key modes. When omitted, the API falls back to the public key's own live/test mode.

// On the Simplr client (forwarded to simplr.flags):
const simplr = new Simplr({ apiKey, publicKey, environment: "uat" });

// Or standalone:
import { SimplrFlags } from "@simplr-ai/node";
const flags = new SimplrFlags({ publicKey, environment: "uat" });
await flags.initialize();

You can also use SimplrFlags standalone.

Profiles (simplr.profiles)

Anonymous user profiles + order fraud monitoring. Identify a user, score orders, read a user's risk, and report outcomes back to improve scoring.

// Create/update an anonymous profile and (optionally) link a device.
const { profile, is_new } = await simplr.profiles.identify("user-123", {
  profileType: "customer",
  fingerprintHash: "9f2a…", // from a client device-signal collector
});

// Score an order.
const result = await simplr.profiles.submitOrder({
  order_id: "order-1",
  external_id: "user-123",
  amount: 4999,
  currency: "USD",
});

// Read a user's current risk profile.
const risk = await simplr.profiles.getProfileRisk("user-123");

// Feed back a confirmed outcome (chargeback, manual review, …).
await simplr.profiles.reportOutcome("user-123", "fraud"); // or "legitimate"

RUM (simplr.rum)

Server-side Real User Monitoring. Events are batched and flushed to /v1/rum/events. The flush timer is installed with unref(), so it never keeps your process alive. There is no DOM auto-capture on the server — report views/actions/errors/logs explicitly.

simplr.rum.initialize({ applicationId: "my-api", environment: "production" });

simplr.rum.setUser("user-123", { plan: "pro" });
simplr.rum.addAttribute("region", "eu-west-1");

simplr.rum.trackView("POST /checkout");
simplr.rum.trackAction("charge_card", { gateway: "stripe" });
simplr.rum.log("info", "checkout completed", { orderId: "order-1" });

try {
  // …
} catch (err) {
  simplr.rum.trackError(err as Error);
}

await simplr.rum.flush();        // force a flush
await simplr.rum.stopSession();  // emit session_end, flush, stop timer

AI delegation (simplr.ai)

OAuth-like AI authentication — mint, validate, and revoke delegation tokens that an end user shares with their AI agent.

// Mint a token (only returned once).
const delegation = await simplr.ai.createDelegation({
  userId: "user-123",
  binding: "verified_device",
  expiresInDays: 7,
  fingerprintHash: "9f2a…",
});

// Validate (introspect) an incoming token on your AI gateway.
const check = await simplr.ai.validate(token, { aiProvider: "anthropic", action: "read_orders" });
if (!check.valid) { /* reject */ }

// Manage delegations.
await simplr.ai.list("user-123");
await simplr.ai.get(delegation.delegationId);
await simplr.ai.stats();
await simplr.ai.revoke(delegation.delegationId, "user revoked");
await simplr.ai.revokeAllForUser("user-123", "logout"); // returns count

The browser SDK's interactive connect() popup flow is web-only and is intentionally omitted from the server SDK.

Admin / measurement (SimplrAdmin)

Dashboard operations — usage/measurement, feature-flag CRUD, and RUM analytics — require a portal token (JWT), not an API key:

import { SimplrAdmin } from "@simplr-ai/node";

const admin = new SimplrAdmin({ token: process.env.SIMPLR_PORTAL_TOKEN! });

await admin.usage.stats(orgId);     // usage counters
await admin.usage.billing(orgId);   // per-service totals + estimated cost (API measurement)
await admin.flags.create(orgId, { key: "new-checkout", environment: "test", rollout_percentage: 10 });
await admin.flags.update(orgId, flagId, { rollout_percentage: 50 });
await admin.rum.overview(orgId, { application_id: "my-app" });
await admin.rum.sessions(orgId, { page: 1, limit: 50 });

Errors

Non-2xx responses throw SimplrError with .status and .body.

License

Commercial software — see LICENSE.