@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

``bash
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

$3

`typescript
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);
}
}
`

$3

`typescript
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');
}
}
`

$3

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

if (isValidEmail('user@example.com')) {
console.log('Valid email format');
}
`

$3

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

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

$3

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

// Validate SDK version format
isValidSdkVersion('@vouch-in/js@1.0.0'); // true

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

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

API Reference

$3

| 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 |

$3

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

$3

| 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.