@cloak-business/sdk

Official JavaScript/TypeScript SDK for the cloak.business PII detection and anonymization API.

Installation

npm install @cloak-business/sdk

Quick Start

import { CloakClient } from '@cloak-business/sdk';

const client = new CloakClient({
  apiKey: 'cb_your_api_key_here',
});

// Analyze text for PII
const analysis = await client.analyze({
  text: 'Contact John Doe at [email protected]',
});

console.log(analysis.results);
// [
//   { entity_type: 'PERSON', start: 8, end: 16, score: 0.85 },
//   { entity_type: 'EMAIL_ADDRESS', start: 20, end: 36, score: 1.0 }
// ]

Features

• Full TypeScript support with comprehensive type definitions
• Automatic retry with exponential backoff on network/server errors
• Rate limit handling with retry-after support
• Request timeout configuration
• Custom fetch implementation support (for testing or special environments)

API Reference

Configuration

const client = new CloakClient({
  apiKey: 'cb_your_api_key_here',  // Required: Your API key
  baseUrl: 'https://cloak.business/api',  // Optional: API base URL
  timeout: 30000,  // Optional: Request timeout in ms (default: 30000)
  retries: 3,      // Optional: Retry count on 5xx/network errors (default: 3)
});

Text Analysis

analyze(request)

Detect PII entities in text.

const result = await client.analyze({
  text: 'My email is [email protected] and my SSN is 123-45-6789',
  language: 'en',              // Optional: ISO 639-1 language code
  entities: ['EMAIL_ADDRESS', 'US_SSN'],  // Optional: Filter entity types
  score_threshold: 0.5,        // Optional: Minimum confidence (0.0-1.0)
});

batchAnalyze(request)

Analyze multiple texts in a single request (max 50 texts).

const result = await client.batchAnalyze({
  texts: [
    'Contact [email protected]',
    'Call me at 555-1234',
  ],
  language: 'en',
});

Anonymization

anonymize(request)

Anonymize detected PII entities using various operators.

const result = await client.anonymize({
  text: 'Contact John at [email protected]',
  analyzer_results: analysis.results,
  operators: {
    PERSON: { type: 'replace', new_value: '[NAME]' },
    EMAIL_ADDRESS: { type: 'hash', hash_type: 'sha256' },
    DEFAULT: { type: 'redact' },  // Fallback for other types
  },
});

Available Operators:

| Operator | Description | Options | |----------|-------------|---------| | replace | Replace with custom text | new_value | | redact | Remove completely | - | | hash | One-way hash | hash_type: 'sha256' or 'sha512' | | mask | Partial masking | masking_char, chars_to_mask, from_end | | encrypt | Reversible encryption | key (16/24/32 chars) | | keep | Leave unchanged | - |

deanonymize(request)

Decrypt encrypted PII entities.

const decrypted = await client.deanonymize({
  text: encrypted.text,
  anonymizer_results: encrypted.items,
  deanonymizers: {
    PERSON: { type: 'decrypt', key: 'my-32-character-secret-key!!' },
    EMAIL_ADDRESS: { type: 'decrypt', key: 'my-32-character-secret-key!!' },
  },
});

Image Processing

processImage(request)

Detect or redact PII in images.

// Analyze mode - returns detected entities
const analysis = await client.processImage({
  file: './document.png',  // File path, Buffer, or Blob
  mode: 'analyze',
  language: 'en',
});

// Redact mode - returns image buffer
const redactedBuffer = await client.processImage({
  file: imageBuffer,
  mode: 'redact',
  fill_color: 'black',  // 'black', 'white', 'red', 'green', 'blue', 'gray'
});

Account Management

// Get token balance
const balance = await client.getTokenBalance();
console.log(`Tokens: ${balance.balance}`);

// List encryption sessions
const sessions = await client.getSessions();

// Delete a session
await client.deleteSession('session-id');

Utility Methods

// Get API limits
const limits = await client.getLimits();

// Get available presets
const presets = await client.getPresets();

// Get all entity types
const entities = await client.getEntities();

// Health check
const health = await client.health();

Error Handling

The SDK provides typed errors for different failure scenarios:

import {
  CloakClient,
  AuthenticationError,
  RateLimitError,
  InsufficientTokensError,
  ValidationError,
} from '@cloak-business/sdk';

try {
  await client.analyze({ text: 'test' });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof InsufficientTokensError) {
    console.error('Not enough tokens');
  } else if (error instanceof ValidationError) {
    console.error('Invalid request:', error.details);
  }
}

Requirements

• Node.js 18.0.0 or higher
• Browser environments with native fetch support

License

MIT