@rogue-security/sdk

Official TypeScript SDK for the Rogue Security AppSec evaluation API.

Wraps the two public AppSec methods, evaluate (inline checks) and invoke (saved guardrail), with full typing, typed errors, automatic retries (via async-retry), and debug logging. Runs in Node 18+, Bun, and edge runtimes.

Server-side only. The SDK authenticates with a long-lived rsk_ API key. Never bundle it into browser/frontend code, where it would be exposed to end users. Call the SDK from your backend, or proxy requests through a server you control.

Install

npm install @rogue-security/sdk
# or: bun add @rogue-security/sdk

Quickstart

import { RogueClient } from "@rogue-security/sdk";

const rogue = new RogueClient({ apiKey: process.env.ROGUE_API_KEY });

const result = await rogue.evaluate({
  messages: [
    { role: "user", content: "What is the patient's SSN?" },
    { role: "assistant", content: "It is 123-45-6789." },
  ],
  piiCheck: true,
  promptInjections: true,
});

console.log(result.status, result.score);
for (const group of result.evaluationResults) {
  for (const r of group.results) {
    if (r.flagged) console.log(group.type, r.label, r.reason);
  }
}

apiKey falls back to the ROGUE_API_KEY environment variable if omitted.

Invoke a saved guardrail

const result = await rogue.invoke({
  guardrailId: "gr_abc123",
  messages: [
    { role: "user", content: userPrompt },
    { role: "assistant", content: modelResponse },
  ],
});

if (result.blocked) {
  // the guardrail's workspace is set to block and the evaluation failed
}

Error handling

Every non-2xx maps to a typed error subclass of RogueError:

import { RogueAuthError, RogueValidationError, RogueError } from "@rogue-security/sdk";

try {
  await rogue.evaluate({ piiCheck: true });
} catch (err) {
  if (err instanceof RogueAuthError) { /* bad / missing key */ }
  else if (err instanceof RogueValidationError) { /* 422, e.g. no checks enabled */ }
  else if (err instanceof RogueError) { console.error(err.status, err.message); }
}

RogueServerError (5xx) and rate limits (429) and network/timeout failures are retried automatically (default 2 retries, exponential backoff with jitter).

Options

new RogueClient({
  apiKey: "rsk_...",
  baseUrl: "http://localhost:8006", // local dev; defaults to production
  timeoutMs: 30000,
  maxRetries: 2,
  debug: true,                       // or "verbose" to log bodies; env: ROGUE_DEBUG=1
});

Local development

bun install
bun run build
bun run test

More: see ../docs for the full API reference, check descriptions, and examples.