@vouch-in/core

Core utilities and shared types for the Vouch SDK ecosystem. This package provides the foundation for email validation and device fingerprinting across all Vouch SDK implementations.

Installation

npm install @vouch-in/core
# or
pnpm add @vouch-in/core
# or
yarn add @vouch-in/core

Features

• Error Classes - Typed error classes for better error handling
• Type Definitions - Shared TypeScript types for validation and fingerprinting
• Validation Utilities - Email format validation helpers
• Crypto Utilities - SHA-256 hashing for fingerprint generation
• Version Utilities - SDK version parsing and validation

Usage

Error Handling

import {
  VouchError,
  ValidationError,
  NetworkError,
  ConfigurationError,
  isVouchError,
  isNetworkError,
} from '@vouch-in/core';

try {
  await vouch.validate(email);
} catch (error) {
  if (isNetworkError(error)) {
    if (error.statusCode === 401) {
      console.log('Invalid API key');
    } else if (error.statusCode === 429) {
      console.log('Rate limited, retry later');
    }
  } else if (isVouchError(error)) {
    console.log('Vouch SDK error:', error.message);
  }
}

Types

import type {
  VouchOptions,
  ValidationRequest,
  ValidationResponse,
  ValidationAction,
  CheckResult,
  ValidationToggles,
  BaseFingerprint,
  BaseSignals,
} from '@vouch-in/core';

// Configure SDK options
const options: VouchOptions = {
  endpoint: 'https://api.vouch.expert',
  apiVersion: 'latest',
};

// Handle validation responses
function handleResponse(response: ValidationResponse) {
  if (response.recommendation === 'allow') {
    console.log('Email validated successfully');
  }
}

Validation Utilities

import { isValidEmail } from '@vouch-in/core';

if (isValidEmail('[email protected]')) {
  console.log('Valid email format');
}

Crypto Utilities

import { sha256Hex } from '@vouch-in/core';

const hash = await sha256Hex('data to hash');

Version Utilities

import {
  isValidSdkVersion,
  createSdkVersion,
  parseSdkVersion,
} from '@vouch-in/core';

// Validate SDK version format
isValidSdkVersion('@vouch-in/[email protected]'); // true

// Create version string
const version = createSdkVersion('@vouch-in/js', '1.0.0');
// '@vouch-in/[email protected]'

// Parse version string
const parsed = parseSdkVersion('@vouch-in/[email protected]');
// { package: '@vouch-in/js', version: '1.0.0' }

API Reference

Error Classes

| Class | Description | |-------|-------------| | VouchError | Base error class for all Vouch SDK errors | | ValidationError | Thrown when email validation fails | | NetworkError | Thrown when network requests fail (includes statusCode) | | ConfigurationError | Thrown when SDK configuration is invalid |

Type Guards

| Function | Returns | |----------|---------| | isVouchError(error) | error is VouchError | | isValidationError(error) | error is ValidationError | | isNetworkError(error) | error is NetworkError | | isConfigurationError(error) | error is ConfigurationError |

Types

| Type | Description | |------|-------------| | VouchOptions | SDK configuration options | | ValidationRequest | Email validation request payload | | ValidationResponse | Validation API response | | ValidationAction | Enum: ALLOW, BLOCK, FLAG | | CheckResult | Individual validation check result | | ValidationToggles | Toggle settings for validation checks | | BaseFingerprint | Base fingerprint structure | | BaseSignals | Base signal group interface |

Internal Package

This package is primarily intended for internal use within the Vouch SDK ecosystem. While it's published publicly for use by platform-specific SDKs, the API may change between versions.

For end-user applications, use the platform-specific SDKs instead:

• @vouch-in/js - Browser SDK
• @vouch-in/react - React SDK
• @vouch-in/react-native - React Native SDK

License

See LICENSE for details.