@sct/client

Official Node.js/TypeScript SDK for the SCT (Secure Compact Tokenization) API — pseudonymize PII, restore pseudonymized data, detect PII in free text, and optimize LLM token usage, all through one typed client.

Requirements

• Node.js >=18 (uses the global fetch API)
• An SCT API key (get one here)

Installation

npm install @sct/client

Quick Start

import { SCTClient } from '@sct/client';

const client = new SCTClient({
  apiKey: process.env.SCT_API_KEY!,
  // baseUrl defaults to 'https://sct.simosphereai.com/api/v1'
});

const result = await client.pseudonymize(
  JSON.stringify({
    name: 'Max Mustermann',
    email: '[email protected]',
    iban: 'DE89370400440532013000',
  }),
  { format: 'json', autoDetectPii: true },
);

console.log(result.pseudonymized_data);
console.log(result.encryption_key);

Configuration

const client = new SCTClient({
  apiKey: 'sct_your_api_key',
  baseUrl: 'https://sct.simosphereai.com/api/v1', // optional
  timeoutMs: 10_000, // optional, aborts the request after this duration
});

API

pseudonymize(data, options?)

Replace PII in structured or free-text data with reversible pseudonyms.

const result = await client.pseudonymize(csvData, {
  format: 'csv',
  method: 'aes-256-gcm', // 'aes-256-gcm' | 'fpe-ff1'
  fields: ['name', 'email'], // only pseudonymize these fields
  // excludeFields: ['amount', 'currency'], // ...or exclude these instead
  autoDetectPii: true, // NLP-based PII detection
});

// result.pseudonymized_data
// result.encryption_key
// result.fields_encrypted
// result.detected_entities
// result.record_count

dePseudonymize(data, encryptionKey, options?)

Restore data that was previously pseudonymized, using the key returned by pseudonymize.

const restored = await client.dePseudonymize(result.pseudonymized_data, result.encryption_key, {
  format: 'json',
});

console.log(restored.original_data);

detectPii(text)

Scan free text for PII entities (names, emails, phone numbers, IBANs, addresses, IDs, IP addresses) without pseudonymizing it.

const detection = await client.detectPii('Contact Max Mustermann at [email protected].');

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

optimizeTokens(text, targetModel?)

Reduce LLM token consumption for a piece of text while preserving its meaning.

const optimized = await client.optimizeTokens(
  'Your verbose text content that could be optimized...',
  'gpt-4o', // any model id the service supports; free string
);

console.log(optimized.optimized_text);
console.log(`${optimized.reduction_percent}% smaller (${optimized.tokens_saved} tokens saved)`);

compressOutput(text, options?)

Compress bulky text — tool/observation output, logs, structured test/CI output, or prose — so it costs fewer LLM tokens while never being larger (in tokens) than the raw input. The service picks the best layer automatically: a format-aware structured parser (pytest, jest, eslint, git-diff, …), the noise-strip engine, or the prose optimizer — guided by the optional format hint or by sniffing the content. The result is tiktoken-verified, so savings_pct >= 0 always.

const compressed = await client.compressOutput(rawPytestOutput, {
  format: 'pytest', // optional hint; omit to let the service sniff the format
  model: 'gpt-4o', // optional; the model the token savings are computed against
  verbosity: 'compact', // 'compact' | 'verbose' | 'ultra'
});

console.log(compressed.compressed);
console.log(`${compressed.savings_pct}% smaller (${compressed.tokens_saved} tokens saved)`);
console.log(compressed.tier); // 'format-aware' | 'prose' | 'raw' | 'error-fallback'

countTokens(text, model?)

Count tokens for a text/model pair without modifying the content.

const { token_count } = await client.countTokens('Your text content here...', 'gpt-4o');

Error Handling

All methods reject with an SCTError on non-2xx responses, network failures, or timeouts.

import { SCTClient, SCTError } from '@sct/client';

try {
  await client.pseudonymize(invalidPayload);
} catch (error) {
  if (error instanceof SCTError) {
    console.error(`SCT API error (${error.statusCode}): ${error.message}`);
    // error.statusCode is 0 for network/timeout failures
  } else {
    throw error;
  }
}

Full Example: PII-Safe LLM Round-Trip

import { SCTClient } from '@sct/client';

const client = new SCTClient({ apiKey: process.env.SCT_API_KEY! });

const prompt = 'Please draft a follow-up email to Max Mustermann ([email protected]).';

// 1. Pseudonymize before sending to an LLM provider
const { pseudonymized_data, encryption_key } = await client.pseudonymize(prompt, {
  format: 'text',
  autoDetectPii: true,
});

// 2. ... send pseudonymized_data to your LLM provider, get llmResponse back ...

// 3. Restore the original PII in the LLM's response
const { original_data } = await client.dePseudonymize(llmResponse, encryption_key, {
  format: 'text',
});

console.log(original_data);

TypeScript

This package ships its own type declarations — no @types package needed. All response and option types are exported from the package root:

import type {
  SCTClientOptions,
  PseudonymizeOptions,
  PseudonymizeResult,
  DePseudonymizeOptions,
  DePseudonymizeResult,
  DetectPIIResult,
  DetectedEntity,
  OptimizeResult,
  TokenCountResult,
  CompressOutputOptions,
  CompressResult,
  CompressTier,
  CompressVerbosity,
  DataFormat,
  EncryptionMethod,
  TokenizerModel,
} from '@sct/client';

License

UNLICENSED — SIMO GmbH internal / commercial use only.