privaro

Privacy Infrastructure for Enterprise AI — Official JavaScript/TypeScript SDK

Zero dependencies. Works in Node.js 18+, browsers, Deno, Bun, and Edge runtimes.

Installation

npm install privaro
# or
pnpm add privaro
# or
yarn add privaro

Quick Start

Protect a prompt

import { PrivaroClient } from "privaro";

const client = new PrivaroClient({
  apiKey: "prvr_...",
  pipelineId: "your-pipeline-uuid",
});

const result = await client.protect(
  "El paciente Juan García, DNI 34521789X, email [email protected]"
);

console.log(result.protected_prompt);
// "El paciente [NM-0001], [ID-0001], email [EM-0001]"

console.log(result.stats.risk_score);    // 0.87
console.log(result.stats.total_detected); // 3
console.log(result.gdpr_compliant);       // true

Detect without masking

const detections = await client.detect("IBAN ES91 2100 0418 4502 0005 1332");

console.log(detections.detections[0]);
// { type: "iban", severity: "critical", confidence: 0.99, detector: "regex" }

Conversation scoping

Pass a conversationId to ensure the same PII maps to the same token across all messages in a conversation:

const convId = "conv-uuid-from-your-db";

const msg1 = await client.protect("Juan García solicita información", convId);
const msg2 = await client.protect("El contrato de Juan García está listo", convId);

// [NM-0001] is the same token in both messages ✓

Agent API

Govern autonomous AI agents under the same privacy policy as human users.

Direct usage

import { AgentRun } from "privaro";

const run = new AgentRun({
  apiKey: "prvr_...",
  pipelineId: "your-pipeline-uuid",
});

try {
  await run.start({
    agentName: "legal-reviewer",
    framework: "custom",
  });

  // Step 1: protect input before sending to LLM
  const step = await run.protect([
    {
      role: "user",
      content: "Review contract for María García DNI 34521789X",
    },
    {
      role: "tool",
      content: "Document found: contrato_garcia_2024.pdf",
      step_type: "tool_output",
    },
  ]);

  // step.protected_messages are safe to send to any LLM
  const llmResponse = await callYourLLM(step.protected_messages);

  // Step 2: restore original values in the final response
  const final = await run.reveal(llmResponse);
  console.log(final.revealed_text); // María García appears in the response

  await run.end("completed");
} catch (error) {
  await run.end("failed");
  throw error;
}

LangChain.js integration

import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createReactAgent } from "langchain/agents";
import { PrivaroCallbackHandler } from "privaro";

const handler = new PrivaroCallbackHandler({
  apiKey: "prvr_...",
  pipelineId: "your-pipeline-uuid",
  agentName: "my-langchain-agent",
  framework: "langchain",
});

const llm = new ChatOpenAI({ callbacks: [handler] });

// All LLM calls and tool outputs are automatically protected
const agent = await createReactAgent({ llm, tools });
const executor = new AgentExecutor({ agent, tools, callbacks: [handler] });

const result = await executor.invoke({ input: "Review this contract..." });

// Reveal tokens in the final output
const revealed = await handler.agentRun.reveal(result.output);

Vercel AI SDK integration

import { streamText } from "ai";
import { openai } from "@ai-sdk/openai";
import { AgentRun } from "privaro";

const run = new AgentRun({ apiKey: "prvr_...", pipelineId: "uuid" });
await run.start({ framework: "vercel-ai" });

const step = await run.protect(userMessage);
const protectedContent = step.protected_messages[0].content;

const { text } = await streamText({
  model: openai("gpt-4o"),
  prompt: protectedContent,
});

const final = await run.reveal(text);
await run.end();

API Reference

PrivaroClient

| Method | Signature | Description | |--------|-----------|-------------| | protect | (prompt, conversationId?, options?) => Promise<ProtectResult> | Detect and tokenize PII | | detect | (prompt) => Promise<DetectResult> | Detect PII without masking |

AgentRun

| Method | Signature | Description | |--------|-----------|-------------| | start | (options?) => Promise<AgentRunStartResult> | Create agent run, get run_id | | protect | (messages, stepIndex?, mode?) => Promise<AgentStepResult> | Protect one step | | reveal | (text) => Promise<AgentRevealResult> | Detokenize final output | | end | (status?) => Promise<AgentRunEndResult> | Close run, finalize counters | | runId | string \| null | Current agent_run_id |

Error handling

import { PrivaroError } from "privaro";

try {
  const result = await client.protect("...");
} catch (error) {
  if (error instanceof PrivaroError) {
    console.error(error.message);  // "Privaro API error 401"
    console.error(error.status);   // 401
    console.error(error.body);     // { error: "invalid_api_key" }
  }
}

TypeScript

Full TypeScript support with exported types:

import type {
  ProtectResult,
  Detection,
  AgentMessage,
  AgentStepResult,
  PrivaroConfig,
} from "privaro";

Requirements

• Node.js 18+ (uses native fetch)
• Or any modern browser / Deno / Bun / Edge runtime with fetch

License

MIT © 2026 iCommunity Labs · privaro.io