The engine, export by export.

import {
  protect, detect, restore, createStreamRestorer,
  registerDetector, estimateCredits, PLACEHOLDER_INSTRUCTION,
  ProtectError, Vault,
} from 'tightlip';

protect(text: string, opts?: ProtectOptions): ProtectResult
detect(text: string, opts?: ProtectOptions): Detection[]
restore(text: string, vault: Vault): string
createStreamRestorer(vault: Vault): { push(chunk: string): string; flush(): string }
registerDetector(detector: Detector): void
estimateCredits(text: string): number
PLACEHOLDER_INSTRUCTION: string
class ProtectError extends Error { name: 'ProtectError'; cause?: unknown }
class Vault {
  static create(): Vault
  static fromJSON(json: VaultJSON): Vault
  toJSON(): VaultJSON
  get size(): number
  lookup(placeholder: string): string | undefined
  getById(id: string): string | undefined                 // marked internal
  findId(type: EntityType, value: string): string | undefined // marked internal
}

interface ProtectResult {
  text: string;                                  // placeholder text
  vault: Vault;                                  // keep on the device
  detections: Detection[];                       // positions in the original text
  counts: Partial<Record<EntityType, number>>;   // distinct values per type
}
interface Detection {
  type: EntityType; start: number; end: number; text: string;
  confidence: number;                            // 0 to 1
  detector: string;                              // for example 'email' or 'name-dictionary'
}
interface Detector {
  id: string;
  types: EntityType[];
  detect(text: string, ctx: { profile: Profile }): Detection[];
}

const input = 'Send the Harrow Lane file from Brightwater Clinic to Ines Okonkwo before Friday.';

protect(input).text;
protect(input, { customTerms: [{ term: 'Harrow Lane' }] }).text;
protect(input, {
  customTerms: [{ term: 'Harrow Lane' }],
  allowTerms: ['Brightwater Clinic'],
}).text;

const input = 'Email Tobias Lindqvist at tobias.l@example.com or call (415) 555-0199.';

protect(input, { types: ['EMAIL'] }).text;
detect(input).map(({ type, text, confidence }) => [type, text, confidence]);
protect(input, { minConfidence: 0.95 }).text;

const input = 'Patient Bartholomew Okafor was seen on 08/02/2026. Call him on (206) 555-0142.';
for (const profile of ['general', 'legal', 'healthcare', 'finance', 'developer']) {
  console.log(profile.padEnd(11), protect(input, { profile }).text);
}

const vault = Vault.create();
const turn1 = protect('Our client Marisol Quintero disputes the charge.', { vault });
const turn2 = protect('Ms. Quintero sent a second email from marisol.q@example.com.', { vault });
console.log(turn1.text);
console.log(turn2.text);
console.log(vault.size);
console.log(vault.lookup('[PERSON_1]'));
console.log(vault.lookup('PERSON_1_LAST'));

// Save and load. Store the JSON where only your app can read it.
const saved = JSON.stringify(vault.toJSON());
const reloaded = Vault.fromJSON(JSON.parse(saved));
console.log(Object.keys(vault.toJSON()));

const reply = 'I have drafted a note to [PERSON_1] and will reply from [EMAIL_1]. [PERSON_1_LAST] will see it today.';
console.log(restore(reply, reloaded));

const { vault } = protect('Our client Rosalind Achterberg called.');
restore("Thanks, PERSON_1. **[Person_1]** and [PERSON 1] and \\[PERSON\\_1\\] and [PERSON_1]'s file. [PERSON_9] is unknown.", vault);

const { vault } = protect(
  'Our client Rosalind Achterberg, Case No. 2:25-cv-01482, called.',
  { profile: 'legal' },
);
const restorer = createStreamRestorer(vault);
for (const chunk of [
  'Dear [PER',
  'SON_1], the hearing for [CASE_NUM',
  'BER_1] is set. Regards, [PERSON_1_LA',
  'ST] team',
]) {
  process.stdout.write(restorer.push(chunk));
}
process.stdout.write(restorer.flush());

const r = createStreamRestorer(vault);
r.push('See you soon, [PERSON_1_LA'); // the stream ends here
r.flush();

estimateCredits('');                                       // 0
estimateCredits('Our client Rosalind Achterberg called.'); // 1
estimateCredits('x'.repeat(32000));                        // 1
estimateCredits('x'.repeat(32001));                        // 2
estimateCredits('x'.repeat(100000));                       // 4

registerDetector({
  id: 'docs-example-detector',
  types: ['CUSTOM'],
  detect() {
    throw new Error('model not loaded');
  },
});

try {
  protect('Our client Rosalind Achterberg called.');
} catch (e) {
  console.log(e instanceof ProtectError, e.name);
  console.log(e.message);
  // Do not send anything.
}

// The same id replaces a detector. This one finds nothing.
registerDetector({ id: 'docs-example-detector', types: ['CUSTOM'], detect: () => [] });
console.log(protect('Our client Rosalind Achterberg called.').text);