Utilities

@alviere/core exports three utility classes: Validator, Cryptor, and Logger. You can get instances from AlviereCore or create them independently via static methods.

Validator

The Validator performs client-side field validation. Each method accepts the value to test and returns null on success, or a human-readable error string on failure.

const validator = AlviereCore.createValidator();

// Returns null (valid)
const result = validator.credit_card_number('4111111111111111');

// Returns "Invalid card number" (or similar)
const result = validator.credit_card_number('1234');

Return vs throw: Validator methods return an error string (or null). This is different from PaymentProcessor.validate* methods, which throw on invalid input. Use Validator directly when you need to display field-level errors in your UI without triggering an exception.

Card fields

Method	Parameters	Description
`credit_card_name(name)`	`string`	Cardholder name
`credit_card_number(number)`	`string`	Card PAN (Luhn check + length)
`credit_card_expiry_date(expiry)`	`string`	Expiry in `MM/YY` format
`credit_card_sec_code(code)`	`string`	CVV / security code
`credit_card_zip_code(zip)`	`string`	Billing ZIP code
`credit_card_pin(pin)`	`string`	Card PIN

Identity and contact

Method	Parameters	Description
`email(email)`	`string`	RFC-compliant email
`phone(phone)`	`string`	Phone number
`date(date, format?)`	`string, 'YYYY-MM-DD'?`	Date string

Generic validators

Method	Parameters	Description
`required(value, fieldName?)`	`string \| null \| undefined, string?`	Rejects empty/null/undefined
`min_length(value, minLength, fieldName?)`	`string, number, string?`	Minimum character count
`max_length(value, maxLength, fieldName?)`	`string, number, string?`	Maximum character count
`pattern(value, pattern, errorMessage?)`	`string, RegExp, string?`	Custom regex match
`numeric(value, fieldName?)`	`string, string?`	Digits only
`alphabetic(value, fieldName?)`	`string, string?`	Letters only
`alphanumeric(value, fieldName?)`	`string, string?`	Letters and digits
`nameField(value, fieldName?)`	`string, string?`	Name field (allows letters, spaces, hyphens)
`url(url)`	`string`	Valid URL
`postal_code(code, country?)`	`string, string?`	Postal code; defaults to `'US'` format
`is_valid_uuid(uuid)`	`string`	UUID v4 format

Example: form validation

const validator = AlviereCore.createValidator();

function validateCardForm(form: { number: string; name: string; expiry: string; cvv: string }) {
  const errors: Record<string, string> = {};

  const numberError = validator.credit_card_number(form.number);
  if (numberError) errors.number = numberError;

  const nameError = validator.credit_card_name(form.name);
  if (nameError) errors.name = nameError;

  const expiryError = validator.credit_card_expiry_date(form.expiry);
  if (expiryError) errors.expiry = expiryError;

  const cvvError = validator.credit_card_sec_code(form.cvv);
  if (cvvError) errors.cvv = cvvError;

  return errors; // empty object = all valid
}

Cryptor

Cryptor encrypts and decrypts request/response payloads using RSA-wrapped AES-GCM. It is used internally by the service layer for sensitive calls.

const cryptor = core.getCryptor();

const encrypted = await cryptor.encrypt({ card_number: '4111111111111111' });

encrypt throws if publicCertificate and publicCertificateId are not set in AlviereCore's configuration. Ensure both are provided before calling any service method that encrypts data.

Method	Parameters	Returns
`encrypt(data)`	`object`	`Promise<EncryptedRequest>`
`decrypt(data)`	`EncryptedResponse`	`Promise<object>`

The service layer calls encrypt/decrypt automatically for endpoints that require it. You rarely need to call Cryptor directly unless you are building a custom service wrapper.

Logger

Logger wraps console output. Debug messages are only emitted when debug: true is set in the core configuration; all other log levels are also silent unless debug mode is on.

const logger = core.getLogger();

logger.debug('Resolving account…');   // emitted only in debug mode
logger.info('Token refreshed');       // also silent unless debug: true
logger.error('Request failed');       // also silent unless debug: true

All log levels are suppressed unless debug: true is configured. If you rely on logger.error() for observability, ensure debug mode is enabled in non-production environments, or pipe errors through your own logging integration.

Method	Parameters	Description
`debug(msg)`	`string`	Debug-level message
`info(msg)`	`string`	Informational message
`warning(msg)`	`string`	Warning (alias: `warn`)
`warn(msg)`	`string`	Alias for `warning`
`error(msg)`	`string`	Error message
`isDebugEnabled()`	—	Returns `true` if debug mode is on

Services

Types & Enums