@veilio/sdk

Official JavaScript/TypeScript SDK for Veilio - Data tokenization and cyber-resilience API.

Installation

npm install @veilio/sdk

Quick Start

import { VeilioClient } from '@veilio/sdk';

const veilio = new VeilioClient({
  apiKey: 'your-api-key-here'
});

// Tokenize sensitive data
const result = await veilio.tokenize({
  data: '[email protected]',
  type: 'email'
});

console.log('Token:', result.token);

// Detokenize when needed
const original = await veilio.detokenize({
  token: result.token,
  reason: 'Send email notification'
});

console.log('Original:', original.data);

Features

• ✅ Simple tokenization - Tokenize single fields
• ✅ Bulk operations - Tokenize/detokenize multiple fields at once
• ✅ Multi-format support - JSON, CSV, SQL formats
• ✅ TypeScript support - Full type definitions included
• ✅ Automatic retries - Handles rate limits and network errors
• ✅ Error handling - Clear error messages and types

API Reference

Constructor

const client = new VeilioClient({
  apiKey: string,           // Required: Your Veilio API key
  baseUrl?: string,        // Optional: API base URL (default: https://api.veilio.com/api)
  timeout?: number,        // Optional: Request timeout in ms (default: 30000)
  maxRetries?: number      // Optional: Max retries for failed requests (default: 3)
});

Methods

tokenize(options)

Tokenize a single field.

const result = await client.tokenize({
  data: '[email protected]',
  type: 'email',           // Optional
  metadata: { ... }       // Optional
});

// Returns: { token: string, createdAt: string }

tokenizeBulk(options)

Tokenize multiple fields in one request.

const result = await client.tokenizeBulk({
  fields: [
    { data: '[email protected]', type: 'email' },
    { data: '+33612345678', type: 'phone' }
  ]
});

// Returns: { tokens: [...], summary: {...}, errors?: [...] }

detokenize(options)

Detokenize a single token.

const result = await client.detokenize({
  token: 'tok_abc123...',
  reason: 'Send email'     // Optional
});

// Returns: { data: string, accessedAt: string }

detokenizeBulk(options)

Detokenize multiple tokens in one request.

const result = await client.detokenizeBulk({
  tokens: [
    { token: 'tok_abc123...', reason: 'Processing' },
    { token: 'tok_def456...', reason: 'Processing' }
  ]
});

// Returns: { results: [...], summary: {...}, errors?: [...] }

tokenizeFormat(options)

Tokenize structured data (JSON, CSV, SQL).

const result = await client.tokenizeFormat({
  data: JSON.stringify({ email: '[email protected]' }),
  format: 'json',          // Optional: auto-detected if omitted
  options: {
    fields: ['email']      // Optional: tokenize only specific fields
  }
});

// Returns: { format: string, tokenizedData: string, tokens: [...], summary: {...} }

detokenizeFormat(options)

Detokenize structured data.

const result = await client.detokenizeFormat({
  tokenizedData: '{...}',
  format: 'json',
  tokens: [
    { path: 'email', token: 'tok_abc123...' }
  ]
});

// Returns: { format: string, detokenizedData: string, summary: {...} }

Examples

Basic Usage

import { VeilioClient } from '@veilio/sdk';

const veilio = new VeilioClient({
  apiKey: process.env.VEILIO_API_KEY
});

// Tokenize
const token = await veilio.tokenize({
  data: '[email protected]',
  type: 'email'
});

// Store token in your database
await db.users.create({
  email: token.token  // Store token, not original data
});

// Later, detokenize when needed
const user = await db.users.findUnique({ where: { id: userId } });
const email = await veilio.detokenize({
  token: user.email,
  reason: 'Send notification'
});

Bulk Operations

// Tokenize multiple fields at once
const result = await veilio.tokenizeBulk({
  fields: [
    { data: '[email protected]', type: 'email' },
    { data: '+33612345678', type: 'phone' },
    { data: '123-45-6789', type: 'ssn' }
  ]
});

// Check for errors
if (result.summary.failed > 0) {
  console.error('Some fields failed:', result.errors);
}

// Use the tokens
result.tokens.forEach((tokenResult, index) => {
  console.log(`Field ${index}: ${tokenResult.token}`);
});

Format Tokenization

// Tokenize JSON data
const jsonData = JSON.stringify({
  users: [
    { email: '[email protected]', phone: '+33612345678' }
  ]
});

const result = await veilio.tokenizeFormat({
  data: jsonData,
  format: 'json'
});

// Store tokenized JSON
await db.save(result.tokenizedData);

// Later, detokenize
const recovered = await veilio.detokenizeFormat({
  tokenizedData: result.tokenizedData,
  format: 'json',
  tokens: result.tokens.map(t => ({ path: t.path, token: t.token }))
});

Error Handling

import { VeilioClient, VeilioError } from '@veilio/sdk';

try {
  const result = await veilio.tokenize({ data: 'test' });
} catch (error) {
  if (error instanceof VeilioError) {
    console.error('API Error:', error.code, error.message);
    console.error('Status:', error.statusCode);
    console.error('Details:', error.details);
  } else {
    console.error('Network error:', error);
  }
}

Error Codes

• AUTH_ERROR - Invalid or missing API key
• VALIDATION_ERROR - Invalid request data
• RATE_LIMIT_ERROR - Rate limit exceeded
• INTERNAL_ERROR - Server error

TypeScript

Full TypeScript support is included:

import { VeilioClient, type TokenizeResult } from '@veilio/sdk';

const client = new VeilioClient({
  apiKey: process.env.VEILIO_API_KEY!
});

const result: TokenizeResult = await client.tokenize({
  data: '[email protected]',
  type: 'email'
});

Requirements

• Node.js 18+ (for native fetch) or install node-fetch for older versions
• A valid Veilio API key

License

MIT

Support

• Documentation: https://docs.veilio.xyz
• Support: [email protected]