Typed client for the OGuardAI API with automatic session management, error handling, and full TypeScript type exports

The @oguardai/sdk package provides a typed client for the OGuardAI API with automatic session management.

Install

npm install @oguardai/sdk
# or
pnpm add @oguardai/sdk

Basic Usage

Transform and Rehydrate

import { OGuardAIClient } from "@oguardai/sdk";

const client = new OGuardAIClient({
  baseUrl: "http://localhost:3000",
  apiKey: "your-api-key", // optional
});

// Transform: replace PII with semantic tokens
const result = await client.transform({
  input: "Contact Julia Schneider at julia@firma.de",
  policy: "default",
});

console.log(result.safe_text);
// "Contact `{{person:p_001}}` at `{{email:e_001}}`"

// Send safe_text to your LLM
const llmResponse = await callYourLLM(result.safe_text, result.entity_context);

// Rehydrate: restore real values in LLM output
const restored = await client.rehydrate({
  output: llmResponse,
  session_state: result.session_state,
  output_channel: "customer_email",
  restore_mode: "formatted",
});

console.log(restored.restored_text);
// "Dear Frau Julia Schneider, ..."

Detect Only

const detection = await client.detect({
  input: "Email: test@example.com, SSN: 123-45-6789",
  threshold: 0.5,
});

for (const entity of detection.entities) {
  console.log(`${entity.type}: ${entity.value} (confidence: ${entity.confidence})`);
}

Health and Capabilities

const health = await client.health();
console.log(health.status); // "healthy"

const caps = await client.capabilities();
console.log(caps.entity_types.map(e => e.name));
// ["person", "email", "phone", "iban", "ssn", ...]

Session Management

For multi-turn conversations, use OGuardAISession to automatically carry session state between calls:

import { OGuardAIClient, OGuardAISession } from "@oguardai/sdk";

const client = new OGuardAIClient({ baseUrl: "http://localhost:3000" });
const session = new OGuardAISession(client, "german-support");

// Turn 1
const turn1 = await session.transform("Ich bin Anna Mueller, Kundennummer 948221");
console.log(turn1.safe_text);
// "Ich bin `{{person:p_001}}`, Kundennummer `{{customer_id:cid_001}}`"

const llmReply1 = "Guten Tag `{{person:p_001}}`, wie kann ich helfen?";
const restored1 = await session.rehydrate(llmReply1, "customer_email");

// Turn 2: same session, entities are deduplicated
const turn2 = await session.transform("Meine E-Mail ist anna@example.com");
// Anna Mueller is still `{{person:p_001}}`

withSession Helper

import { OGuardAIClient, withSession } from "@oguardai/sdk";

const client = new OGuardAIClient({ baseUrl: "http://localhost:3000" });

await withSession(client, "default", async (session) => {
  const result = await session.transform("Hello, I am John Smith");
  // ... call LLM ...
  const restored = await session.rehydrate(llmOutput, "user_output");
});

Error Handling

The SDK throws typed errors for different failure modes:

import {
  OGuardAIClient,
  OGuardAIError,
  ValidationError,
  AuthError,
  SessionExpiredError,
  PolicyDeniedError,
  TimeoutError,
} from "@oguardai/sdk";

const client = new OGuardAIClient({ baseUrl: "http://localhost:3000" });

try {
  await client.transform({ input: "some text" });
} catch (error) {
  if (error instanceof ValidationError) {
    // 400: malformed request
    console.error("Invalid request:", error.message);
  } else if (error instanceof AuthError) {
    // 401/403: authentication failed
    console.error("Auth error:", error.message);
  } else if (error instanceof SessionExpiredError) {
    // 410: session TTL elapsed
    console.error("Session expired, create a new one");
  } else if (error instanceof PolicyDeniedError) {
    // Entity blocked by policy
    console.error("Policy blocked entity:", error.message);
  } else if (error instanceof TimeoutError) {
    // Request timed out
    console.error("Request timed out");
  } else if (error instanceof OGuardAIError) {
    // Other API error
    console.error(`Error [${error.code}]: ${error.message}`);
  }
}

Configuration

const client = new OGuardAIClient({
  baseUrl: "http://localhost:3000",  // Required
  apiKey: "your-api-key",           // Optional: sent as X-API-Key header
  timeout: 30000,                   // Optional: request timeout in ms (default: 30000)
});

Types

All request/response types are exported:

import type {
  TransformRequest,
  TransformResponse,
  RehydrateRequest,
  RehydrateResponse,
  DetectRequest,
  DetectResponse,
  HealthResponse,
  CapabilitiesResponse,
  EntityContext,
  EntityInfo,
  RestoreMode,
  OutputChannel,
} from "@oguardai/sdk";

TypeScript SDK