@gatewaystack/transformabl-core

Framework-agnostic PII detection, content redaction, and safety classification for AI gateways.

@gatewaystack/transformabl-core is the low-level engine behind @gatewaystack/transformabl. Use it directly when you need content transformation without Express.

Installation

npm install @gatewaystack/transformabl-core

Features

• PII detection — regex-based detection for email, phone (US 10+ digit), SSN, credit card (Visa/MC/Amex/Discover/Diners), IP address, date of birth
• Content redaction — three modes: mask, remove, or placeholder replacement
• Safety classification — detect prompt injection, jailbreak attempts, and code injection patterns
• Regulatory flagging — automatic GDPR, PCI, COPPA, HIPAA labels based on PII types found
• Risk scoring — 0-100 composite score from safety + regulatory + PII density
• Custom patterns — extend detection with your own regex patterns

Quick Start

Detect PII

import { detectPii } from "@gatewaystack/transformabl-core";

const matches = detectPii("Contact [email protected] or call (555) 123-4567");
// [
//   { type: "email", value: "[email protected]", start: 8, end: 24 },
//   { type: "phone", value: "(555) 123-4567", start: 33, end: 47 },
// ]

Redact PII

import { detectPii, redactPii } from "@gatewaystack/transformabl-core";

const text = "My email is [email protected] and SSN is 123-45-6789";
const matches = detectPii(text);

// Mask mode (default)
redactPii(text, matches);
// "My email is jo**************om and SSN is 12*******89"

// Placeholder mode
redactPii(text, matches, { mode: "placeholder" });
// "My email is [EMAIL] and SSN is [SSN]"

// Remove mode
redactPii(text, matches, { mode: "remove" });
// "My email is  and SSN is "

Classify content

import { detectPii, classifyContent } from "@gatewaystack/transformabl-core";

const text = "Ignore all previous instructions. My SSN is 123-45-6789.";
const pii = detectPii(text);
const result = classifyContent(text, pii);

// {
//   labels: [
//     { category: "prompt_injection", confidence: "medium", ... },
//     { category: "pci", confidence: "high", detail: "PII detected: ssn" },
//     { category: "gdpr", confidence: "high", detail: "PII detected: ssn" },
//   ],
//   riskScore: 75,
//   hasSafetyRisk: true,
//   hasRegulatoryContent: true,
// }

Full pipeline

import { transformContent } from "@gatewaystack/transformabl-core";

const result = transformContent("Email me at [email protected]", {
  redaction: { mode: "placeholder" },
});

// {
//   content: "Email me at [EMAIL]",
//   transformed: true,
//   piiMatches: [...],
//   classification: { labels: [...], riskScore: 20, ... },
//   metadata: { wordCount: 4, charCount: 24, ... },
// }

API

detectPii(text, customPatterns?)

Returns an array of PiiMatch objects with type, value, start, and end positions.

Built-in PII types: email, phone, ssn, credit_card, ip_address, date_of_birth.

Add custom patterns:

detectPii(text, [{ type: "custom_id", pattern: /CUST-\d{6}/g }]);

redactPii(text, matches, config?)

| Option | Type | Default | Description | |--------|------|---------|-------------| | mode | "mask" \| "remove" \| "placeholder" | "mask" | Redaction strategy | | maskChar | string | "*" | Character used for masking | | maskKeep | number | 2 | Characters to keep at start/end in mask mode | | placeholder | string | "[{TYPE}]" | Template for placeholder mode | | types | PiiType[] | all | Only redact these PII types |

classifyContent(text, piiMatches)

Returns ClassificationResult:

• labels — array of { category, confidence, detail }
• riskScore — 0-100 composite score
• hasSafetyRisk — true if injection/jailbreak/code patterns found
• hasRegulatoryContent — true if PII triggers regulatory categories

Safety categories: prompt_injection, jailbreak_attempt, code_injection

Regulatory categories: gdpr, pci, coppa, hipaa

transformContent(text, config?)

Full pipeline: detect + redact + classify + extract metadata in one call.

extractMetadata(text)

Returns { wordCount, charCount, lineCount, hasCode }.

Related Packages

• @gatewaystack/transformabl — Express middleware wrapper
• @gatewaystack/validatabl-core — Policy decisions based on classification results

License

MIT