Browser SDK

Install

npm install @nopii/browser

Using React? @nopii/react wraps everything on this page in a provider and hooks.

Initialize

Give the SDK a client session from your own backend. Sessions are bound to your user, which is what lets that user reveal their earlier messages later. Your server mints them with @nopii/node or nopii-sdk.

import { NoPII } from "@nopii/browser";

let session: { token: string; expiresAt: number } | undefined;

const nopii = NoPII.init({
  baseUrl: "https://api.nopii.co",
  // Called before each NoPII request. Cache the token and refresh it shortly before it expires.
  sessionToken: async () => {
    if (!session || session.expiresAt - Date.now() < 60_000) {
      const body = await fetch("/api/nopii-session", { method: "POST" }).then((r) => r.json());
      session = { token: body.token, expiresAt: Date.parse(body.expiresAt) };
    }
    return session.token;
  },
});

For development, or an app with no signed-in users, a publishable key works instead: NoPII.init({ baseUrl, publishableKey: "npk_live_..." }). It only works from the origins listed on the key, and reveals are scoped by session id alone. See Keys and reveal policy.

Protect your own routes (Tier 2)

Name the routes that carry messages and where the text is in their bodies. The SDK tokenizes those fields in one batch before the request is sent, then reveals the response as it streams back.

nopii.protect({
  routes: [
    { match: "/api/chat", request: "ai-sdk" },
    { match: "/api/tickets", request: ["subject", "messages[*].body"] },
  ],
});

// Unchanged app code. /api/chat now receives tokens.
await fetch("/api/chat", { method: "POST", body: JSON.stringify({ messages }) });

protect patches the global fetch. To leave it alone, pass patchGlobalFetch: false and hand nopii.fetch to the code that makes the request.

WebSockets

Chat over a socket is protected the same way. Outgoing frames are tokenized in order, and incoming frames are revealed before your listeners see them.

nopii.protect({
  sockets: [{ match: "wss://app.example.com/chat", send: ["message"] }],
});

const socket = new WebSocket("wss://app.example.com/chat"); // protected

A frame that cannot be tokenized is not sent, and the socket fires error. Libraries that load WebSocket before the SDK runs, such as Socket.IO, need nopii.WebSocket passed to them:

import { io, WebSocket } from "socket.io-client";

nopii.protect({
  sockets: [{ match: (url) => url.pathname.startsWith("/socket.io/"), framing: "socket.io", send: ["args[*].text"] }],
  patchGlobalWebSocket: false,
});

class NoPIITransport extends WebSocket {
  createSocket(uri: string, protocols?: string | string[]) {
    return new nopii.WebSocket(uri, protocols);
  }
}

// WebSocket transport only: long polling is not covered.
const socket = io("https://app.example.com", { transports: [NoPIITransport] });

Revealing tokens

For tokenized content that did not arrive through a protected route, such as history loaded separately:

const text = await nopii.reveal("Invoice for [NAME: 8f2kQ1xZ]");

// Every string inside a JSON value
const history = await nopii.revealValue(await fetch("/api/history").then((r) => r.json()));

// Tokens this page already holds, with no network call
const quick = nopii.revealLocal(text);

const observer = nopii.reveal(document.querySelector("#history")!, {
  attributes: ["title"], // optional: attributes to reveal too
});

observer.disconnect(); // or nopii.destroy()

Route browser LLM calls through NoPII (Tier 1)

If your page already calls an LLM provider directly, hand nopii.fetch to the client. Requests to known provider hosts go to NoPII instead, which tokenizes them and reveals the reply.

import OpenAI from "openai";

const openai = new OpenAI({ apiKey, dangerouslyAllowBrowser: true, fetch: nopii.fetch });

Or call nopii.intercept() to patch the global fetch for every provider call on the page. The provider key is authenticated the same way as with the proxy, so register it in the admin console. Supported hosts are OpenAI, Anthropic, xAI, DeepSeek, Mistral, Groq, Together, Fireworks, and Gemini; add others with intercept({ additionalProviders: [{ id, host, basePath }] }).

Tokenizing by hand

const result = await nopii.tokenize("Call John Smith at john@example.com");
result.texts[0];   // "Call [NAME: ...] at [EMAIL: ...]"
result.entities;   // what was found, with offsets into your text

const found = await nopii.detect(draft); // highlight PII before sending; nothing is tokenized

Errors

Cleaning up

nopii.destroy() restores fetch and WebSocket, forgets protected routes, stops DOM observers, and drops the plaintext the instance was holding. Sockets already open stay protected.

More than one instance can patch the globals at once, and they can be destroyed in any order: the others keep protecting. If another library wrapped fetch after NoPII did, its wrapper is left in place.