@edirect/tokenization

Node.js client for the eDirect Tokenization Service. Provides methods to securely tokenize and detokenize sensitive data (PII, payment card data), with built-in caching to reduce service load.

Features

• Tokenize and detokenize arbitrary payloads with a simple API
• Caches service configurations for 5 minutes
• Caches token results for 1 minute to avoid redundant requests
• Token parsing/validation utility (parseToken)
• Supports nested object payloads — sensitive fields are replaced by opaque token strings

Installation

pnpm add @edirect/tokenization
# or
npm install @edirect/tokenization

Quick Start

import { Tokenization } from '@edirect/tokenization';

const tokenization = new Tokenization(
  'https://tokenization-service.internal.example.com'
);

// Tokenize sensitive data
const tokenizedPayload = await tokenization.tokenize(
  authToken, // Bearer token for the tokenization service
  'th-broker', // tenant
  'payment-config', // tokenization configuration name
  {
    name: 'John Doe',
    payment: {
      cardNumber: '4111 1111 1111 1111',
      cvv: '123',
      expirationDate: '12/26',
    },
  }
);

// tokenizedPayload.payment.cardNumber → 'token:th-broker:str:abc123xyz...'
console.log('Tokenized:', tokenizedPayload);

// Detokenize to recover original data
const originalPayload = await tokenization.detokenize(
  authToken,
  'th-broker',
  'payment-config',
  tokenizedPayload
);

console.log('Original:', originalPayload);

Token Format

Tokens follow the format token:{tenant}:{type}:{hash}:

token:th-broker:str:abc123xyz456
  ↑     ↑         ↑   ↑
  |     |         |   hash (the tokenized value)
  |     |         type (str, num, etc.)
  |     tenant
  prefix

parseToken(tokenString)

import { Tokenization } from '@edirect/tokenization';

const parsed = Tokenization.parseToken('token:th-broker:str:abc123xyz456');

console.log(parsed.isToken); // true
console.log(parsed.tenant); // 'th-broker'
console.log(parsed.type); // 'str'
console.log(parsed.Hash); // 'abc123xyz456'

// For non-token strings:
const notToken = Tokenization.parseToken('plain-value');
console.log(notToken.isToken); // false

API

new Tokenization(baseUrl: string)

Creates a tokenization client.

| Parameter | Type | Description | | --------- | -------- | ------------------------------------ | | baseUrl | string | Base URL of the Tokenization Service |

tokenize(auth, tenant, config, payload): Promise<TokenPayload>

Replaces sensitive fields in payload with opaque token strings.

| Parameter | Type | Description | | --------- | -------------- | -------------------------------------------- | | auth | string | Bearer token for the tokenization service | | tenant | string | Tenant identifier (e.g., 'th-broker') | | config | string | Tokenization configuration name | | payload | TokenPayload | Object containing sensitive data to tokenize |

Returns the same payload structure with sensitive fields replaced by token strings.

detokenize(auth, tenant, config, payload): Promise<TokenPayload>

Replaces token strings in payload with their original values.

| Parameter | Type | Description | | --------- | -------------- | ------------------------------------------ | | auth | string | Bearer token for the tokenization service | | tenant | string | Tenant identifier | | config | string | Tokenization configuration name | | payload | TokenPayload | Object containing token strings to resolve |

Returns the original payload with token strings replaced by their actual values.

static parseToken(tokenString: string): ParsedToken

Parses a token string into its components.

| Return Field | Type | Description | | ------------ | --------- | ----------------------------------- | | isToken | boolean | Whether the string is a valid token | | tenant | string | Tenant from the token | | type | string | Data type (e.g., str, num) | | Hash | string | Token hash value |

Caching Behavior

| Cache | Duration | Description | | ------------------- | --------- | -------------------------------------------- | | Configuration cache | 5 minutes | Stores tokenization configs from the service | | Token cache | 1 minute | Stores resolved token values |

After updating tokenization configurations on the service, wait up to 5 minutes for the cache to expire, or restart your service.