SimpleVerify Node.js SDK

Official Node.js/TypeScript client library for the SimpleVerify API. Send and verify SMS codes, email codes, and magic links with a few lines of code.

Requirements

• Node.js 18+

Installation

npm install simpleverify

Quick Start

import { SimpleVerifyClient } from 'simpleverify';

const client = new SimpleVerifyClient('vk_test_your_api_key_here');

// Send an SMS verification
const verification = await client.verifications.send({
  type: 'sms',
  destination: '+15551234567',
});

console.log(verification.verification_id); // "a1b2c3d4-..."
console.log(verification.status);           // "pending"

// Check the code the user entered
const result = await client.verifications.check(verification.verification_id, '482913');

if (result.valid) {
  console.log('Verified!');
}

Usage

Initialize the Client

// With just an API key
const client = new SimpleVerifyClient('vk_test_...');

// With options
const client = new SimpleVerifyClient({
  apiKey: 'vk_test_...',
  baseUrl: 'https://api.simpleverify.io', // default
  timeout: 30000,                          // default, in milliseconds
});

Send a Verification

// SMS
const verification = await client.verifications.send({
  type: 'sms',
  destination: '+15551234567',
});

// Email
const verification = await client.verifications.send({
  type: 'email',
  destination: '[email protected]',
});

// Magic link
const verification = await client.verifications.send({
  type: 'magic_link',
  destination: '[email protected]',
  redirect_url: 'https://yourapp.com/dashboard',
  failure_redirect_url: 'https://yourapp.com/auth/magic-link-result',
});

// With metadata
const verification = await client.verifications.send({
  type: 'sms',
  destination: '+15551234567',
  metadata: { user_id: 42 },
});

The response is a Verification object:

verification.verification_id // UUID
verification.type            // "sms", "email", or "magic_link"
verification.destination     // masked: "*******4567" or "u***@example.com"
verification.status          // "pending"
verification.expires_at      // ISO 8601 datetime
verification.environment     // "test" or "live"

Test Mode

When using a vk_test_ API key, the response includes the code or token so you can complete the flow without real SMS/email delivery:

verification.test?.code   // "482913" (SMS/email)
verification.test?.token  // 64-char string (magic link)

In live mode (vk_live_ key), verification.test is undefined.

If you set failure_redirect_url on a magic link, failed clicks redirect there with status (invalid, expired, or already_used) and verification_id query parameters.

Successful magic link clicks redirect with status=verified, verification_id, and a one-time exchange_code. Redeem that code from your backend:

const exchange = await client.verifications.exchange(verificationId, exchangeCode);

exchange.destination // verified email address
exchange.metadata    // original metadata object

Check a Code

const result = await client.verifications.check(verification.verification_id, '482913');

result.valid            // true or false
result.verification_id  // UUID
result.type             // present when valid
result.destination      // present when valid (masked)

An invalid code returns valid: false (not an error). Only check the valid field.

Get Verification Status

const status = await client.verifications.get(verification.verification_id);

status.status      // "pending", "verified", or "expired"
status.created_at  // ISO 8601 datetime

Error Handling

All API errors throw specific error classes extending SimpleVerifyError:

import {
  SimpleVerifyError,
  AuthenticationError,
  ValidationError,
  RateLimitError,
  NotFoundError,
} from 'simpleverify';

try {
  await client.verifications.send({ type: 'sms', destination: '+15551234567' });
} catch (e) {
  if (e instanceof RateLimitError) {
    console.log(`Rate limited. Retry in ${e.retryAfterSeconds} seconds.`);
  } else if (e instanceof ValidationError) {
    console.log('Validation errors:', e.details);
  } else if (e instanceof AuthenticationError) {
    console.log('Bad API key:', e.errorCode);
  } else if (e instanceof NotFoundError) {
    console.log('Verification not found.');
  } else if (e instanceof SimpleVerifyError) {
    console.log(`Status: ${e.httpStatus}, Code: ${e.errorCode}, Message: ${e.message}`);
  }
}

| HTTP Status | Error Class | |-------------|-------------| | 401 | AuthenticationError | | 404 | NotFoundError | | 422 | ValidationError | | 429 | RateLimitError | | Other | ApiError | | Network failure | ConnectionError |

TypeScript

This package includes full TypeScript type definitions. All request and response types are exported:

import type { SendVerificationRequest, Verification, VerificationCheck, TestData } from 'simpleverify';

License

MIT