xposedornot

Official Node.js SDK for the XposedOrNot API
Check if your email has been exposed in data breaches

---

Note: This SDK uses the free public API from XposedOrNot.com - a free service to check if your email has been compromised in data breaches. Visit the XposedOrNot website to learn more about the service and check your email manually.

---

Table of Contents

• Features
• Installation
• Quick Start
• API Reference
  • checkEmail
  • getBreaches
  • getBreachAnalytics
• Error Handling
• Rate Limits
• TypeScript Support
• Contributing
• License

---

Features

• Simple API - Easy-to-use methods for checking email breaches
• Full TypeScript Support - Complete type definitions included
• Detailed Analytics - Get breach details, risk scores, and metrics
• Error Handling - Custom error classes for different scenarios
• Configurable - Timeout, retries, and custom options
• Secure - HTTPS enforced, input validation, no sensitive data logging

Installation

npm install xposedornot

yarn add xposedornot

pnpm add xposedornot

Requirements

• Node.js 18.0.0 or higher

Quick Start

import { XposedOrNot } from 'xposedornot';

const xon = new XposedOrNot();

// Check if an email has been breached
const result = await xon.checkEmail('test@example.com');

if (result.found) {
  console.log(`Email found in ${result.breaches.length} breaches:`);
  result.breaches.forEach(breach => console.log(`  - ${breach}`));
} else {
  console.log('Good news! Email not found in any known breaches.');
}

API Reference

Constructor

const xon = new XposedOrNot(config?: XposedOrNotConfig);

Configuration Options

Option	Type	Default	Description
baseUrl	string	'https://api.xposedornot.com'	API base URL
timeout	number	30000	Request timeout in milliseconds
retries	number	3	Number of retry attempts
headers	Record<string, string>	{}	Custom headers for all requests

Methods

checkEmail(email, options?)

Check if an email address has been exposed in any data breaches.

const result = await xon.checkEmail('user@example.com');

// Result type:
// {
//   email: string;
//   found: boolean;
//   breaches: string[];
// }

Options:

Option	Type	Description
includeDetails	boolean	Include detailed breach information

getBreaches(options?)

Get a list of all known data breaches.

// Get all breaches
const breaches = await xon.getBreaches();

// Filter by domain
const adobeBreaches = await xon.getBreaches({ domain: 'adobe.com' });

// Get specific breach by ID
const linkedIn = await xon.getBreaches({ breachId: 'linkedin' });

Options:

Option	Type	Description
domain	string	Filter breaches by domain
breachId	string	Get a specific breach by ID

Returns: Array of Breach objects with properties:

• breachID - Unique identifier
• breachedDate - Date of the breach
• domain - Associated domain
• industry - Industry category
• exposedData - Types of data exposed
• exposedRecords - Number of records exposed
• verified - Whether the breach is verified
• And more...

getBreachAnalytics(email, options?)

Get detailed breach analytics for an email address.

const result = await xon.getBreachAnalytics('user@example.com');

if (result.found && result.analytics) {
  console.log('Exposed breaches:', result.analytics.ExposedBreaches);
  console.log('Breach summary:', result.analytics.BreachesSummary);
  console.log('Breach metrics:', result.analytics.BreachMetrics);
  console.log('Paste exposures:', result.analytics.ExposedPastes);
}

Options:

Option	Type	Description
token	string	Token for accessing sensitive data

Error Handling

The library provides custom error classes for different scenarios:

import {
  XposedOrNot,
  XposedOrNotError,
  RateLimitError,
  ValidationError,
  NetworkError,
  TimeoutError,
} from 'xposedornot';

const xon = new XposedOrNot();

try {
  const result = await xon.checkEmail('invalid-email');
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Invalid input:', error.message);
  } else if (error instanceof RateLimitError) {
    console.error('Rate limited. Retry after:', error.retryAfter);
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  } else if (error instanceof TimeoutError) {
    console.error('Request timed out');
  } else if (error instanceof XposedOrNotError) {
    console.error('API error:', error.message, error.code);
  }
}

Error Types

Error Class	Description
XposedOrNotError	Base error class
ValidationError	Invalid input (e.g., malformed email)
RateLimitError	API rate limit exceeded
NotFoundError	Resource not found
AuthenticationError	Authentication failed
NetworkError	Network connectivity issues
TimeoutError	Request timed out
ApiError	General API error

Rate Limits

The XposedOrNot API has the following rate limits:

• 2 requests per second
• 50-100 requests per hour
• 100-1000 requests per day

The client includes automatic retry with exponential backoff for transient failures.

TypeScript Support

This library is written in TypeScript and includes full type definitions:

import type {
  Breach,
  CheckEmailResult,
  BreachAnalyticsResult,
  XposedOrNotConfig,
} from 'xposedornot';

CommonJS Usage

const { XposedOrNot } = require('xposedornot');

const xon = new XposedOrNot();

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/XposedOrNot/XposedOrNot-JS.git
cd XposedOrNot-JS

# Install dependencies
npm install

# Run tests
npm run test:run

# Build
npm run build

# Lint
npm run lint

Projects Using This

Using xposedornot in your project? Let us know!

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• API Status: XposedOrNot Status

Show Your Support

If you find this package useful, give it a ⭐ on GitHub!

License

MIT - see the LICENSE file for details.

Links

• XposedOrNot Website
• API Documentation
• npm Package
• GitHub Repository
• XposedOrNot API Repository

---

Made with ❤️ by XposedOrNot