{"_id":"xposedornot","_rev":"2-a942b3c0cf236591159421c2514c3b81","name":"xposedornot","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"xposedornot","version":"0.1.0","keywords":["xposedornot","breach","databreach","email","osint","leak","breach-detection","email-security","pwned"],"author":{"name":"deva@xposedornot.com"},"license":"MIT","_id":"xposedornot@0.1.0","maintainers":[{"name":"devanand.premkumar","email":"deva@xposedornot.com"}],"homepage":"https://github.com/XposedOrNot/XposedOrNot-JS#readme","bugs":{"url":"https://github.com/XposedOrNot/XposedOrNot-JS/issues"},"dist":{"shasum":"24434c24178edec43ae6be149a2eb7cfef44bd17","tarball":"https://registry.npmjs.org/xposedornot/-/xposedornot-0.1.0.tgz","fileCount":9,"integrity":"sha512-/XvjnbVnPWuNmKWEeMfv3ijAypbiGOIRg9LKlptBXj2beRp+PV/uC69mQw2dCIgFDuQksGMxs2f+MrKFkXbtqQ==","signatures":[{"sig":"MEUCIFsxBOg/NG56SPuOFVqoZYYu0ual90FGm5Jb/0K8NWA5AiEAgWXyX8GfEECe5nJ5xAoFZV1PgXVAavN1fvkw3rNKNKA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":135399},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18.0.0"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"gitHead":"e1fe8cd5c90a75ee60f5b8b4563f4fd4d1ff7984","scripts":{"dev":"tsup --watch","lint":"eslint src/ examples/","test":"vitest","build":"tsup","check":"npm run typecheck && npm run lint && npm run format:check","format":"prettier --write src/ examples/","lint:fix":"eslint src/ examples/ --fix","test:run":"vitest run","typecheck":"tsc --noEmit","format:check":"prettier --check src/ examples/","prepublishOnly":"npm run check && npm run build"},"_npmUser":{"name":"devanand.premkumar","email":"deva@xposedornot.com"},"repository":{"url":"git+https://github.com/XposedOrNot/XposedOrNot-JS.git","type":"git"},"_npmVersion":"9.2.0","description":"Official Node.js client for the XposedOrNot API - Check if your email has been exposed in data breaches","directories":{},"_nodeVersion":"18.19.1","_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","tsup":"^8.0.0","eslint":"^9.39.1","vitest":"^1.0.0","prettier":"^3.7.4","@eslint/js":"^9.39.1","typescript":"^5.3.0","@types/node":"^20.10.0","typescript-eslint":"^8.49.0","eslint-config-prettier":"^10.1.8","eslint-plugin-prettier":"^5.5.4"},"_npmOperationalInternal":{"tmp":"tmp/xposedornot_0.1.0_1765534915957_0.975382485150267","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"xposedornot","version":"0.2.0","description":"Official Node.js client for the XposedOrNot API - Check for data breaches and exposed credentials","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest","test:run":"vitest run","lint":"eslint src/ examples/","lint:fix":"eslint src/ examples/ --fix","format":"prettier --write src/ examples/","format:check":"prettier --check src/ examples/","typecheck":"tsc --noEmit","check":"npm run typecheck && npm run lint && npm run format:check","prepublishOnly":"npm run check && npm run build"},"keywords":["xposedornot","breach","databreach","data-breach","email","password","security","cybersecurity","osint","leak","breach-detection","email-security","pwned"],"author":{"name":"XposedOrNot","email":"deva@xposedornot.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/XposedOrNot/XposedOrNot-JS.git"},"bugs":{"url":"https://github.com/XposedOrNot/XposedOrNot-JS/issues"},"homepage":"https://github.com/XposedOrNot/XposedOrNot-JS#readme","engines":{"node":">=18.0.0"},"devDependencies":{"@eslint/js":"^9.39.1","@types/node":"^20.10.0","eslint":"^9.39.1","eslint-config-prettier":"^10.1.8","eslint-plugin-prettier":"^5.5.4","prettier":"^3.7.4","tsup":"^8.0.0","tsx":"^4.21.0","typescript":"^5.3.0","typescript-eslint":"^8.49.0","vitest":"^1.0.0"},"dependencies":{"js-sha3":"^0.9.3"},"gitHead":"d4cf1af21a53c32c03d767a59d382b01b4a21908","_id":"xposedornot@0.2.0","_nodeVersion":"18.19.1","_npmVersion":"9.2.0","dist":{"integrity":"sha512-ieJQqa90IHNTjh8jU3JDitOl0FQBPiRJml6qNXvjCDVVixhcNu0mdVSQ8jc3V0XAwtFk7Q+Kx54+cJ+LFLOLyg==","shasum":"a3709e6846d49298243b78864b2278fc2a5996da","tarball":"https://registry.npmjs.org/xposedornot/-/xposedornot-0.2.0.tgz","fileCount":9,"unpackedSize":201400,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHTpmeNmquLP0++bUhscLyIBKG51301KXCIWPzPkJZiVAiEAtlX+7xqYTkBX9hHljWpN1QGUszjMI057u5o4dHBPDjI="}]},"_npmUser":{"name":"devanand.premkumar","email":"deva@xposedornot.com"},"directories":{},"maintainers":[{"name":"devanand.premkumar","email":"deva@xposedornot.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/xposedornot_0.2.0_1784389319836_0.31794367024320014"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-12T10:21:55.956Z","modified":"2026-07-18T15:42:00.101Z","0.1.0":"2025-12-12T10:21:56.111Z","0.2.0":"2026-07-18T15:41:59.965Z"},"bugs":{"url":"https://github.com/XposedOrNot/XposedOrNot-JS/issues"},"author":{"name":"XposedOrNot","email":"deva@xposedornot.com"},"license":"MIT","homepage":"https://github.com/XposedOrNot/XposedOrNot-JS#readme","keywords":["xposedornot","breach","databreach","data-breach","email","password","security","cybersecurity","osint","leak","breach-detection","email-security","pwned"],"repository":{"type":"git","url":"git+https://github.com/XposedOrNot/XposedOrNot-JS.git"},"description":"Official Node.js client for the XposedOrNot API - Check for data breaches and exposed credentials","maintainers":[{"name":"devanand.premkumar","email":"deva@xposedornot.com"}],"readme":"

\n \n \"XposedOrNot\"\n \n

\n\n

xposedornot

\n\n

\n Official Node.js SDK for the XposedOrNot API
\n Check for data breaches and exposed credentials\n

\n\n

\n \"npm\n \"Build\n \"License:\n \"Node.js\n \"TypeScript\"\n

\n\n---\n\n> **Note:** This SDK uses the free public API from [XposedOrNot.com](https://xposedornot.com) - a free service to check if your email has been compromised in data breaches. Visit the [XposedOrNot website](https://xposedornot.com) to learn more about the service and check your email manually.\n\n---\n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [API Reference](#api-reference)\n - [checkEmail](#checkemailemail-options)\n - [checkPassword](#checkpasswordpassword)\n - [getBreaches](#getbreachesoptions)\n - [getBreachAnalytics](#getbreachanalyticsemail-options)\n - [getDomainBreaches](#getdomainbreaches)\n- [Plus API (API Key)](#plus-api-api-key)\n- [Error Handling](#error-handling)\n- [Rate Limits](#rate-limits)\n- [TypeScript Support](#typescript-support)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Features\n\n- **Simple API** - Easy-to-use methods for checking email breaches\n- **Password Check** - k-anonymity password exposure check (your password never leaves your machine)\n- **Plus API Support** - Detailed breach data and domain monitoring with an API key\n- **Full TypeScript Support** - Complete type definitions included\n- **Detailed Analytics** - Get breach details, risk scores, and metrics\n- **Error Handling** - Custom error classes for different scenarios\n- **Configurable** - Timeout, retries, and custom options\n- **Rate-Limit Friendly** - Built-in 1 request/second spacing on the free API, plus automatic retries\n- **Secure** - HTTPS enforced, input validation, no sensitive data logging\n\n## Installation\n\n```bash\nnpm install xposedornot\n```\n\n```bash\nyarn add xposedornot\n```\n\n```bash\npnpm add xposedornot\n```\n\n## Requirements\n\n- Node.js 18.0.0 or higher\n\n## Quick Start\n\n```typescript\nimport { XposedOrNot } from 'xposedornot';\n\nconst xon = new XposedOrNot();\n\n// Check if an email has been breached\nconst result = await xon.checkEmail('test@example.com');\n\nif (result.found) {\n console.log(`Email found in ${result.breaches.length} breaches:`);\n result.breaches.forEach(breach => console.log(` - ${breach}`));\n} else {\n console.log('Good news! Email not found in any known breaches.');\n}\n\n// Check if a password has been exposed (hashed locally, never transmitted)\nconst password = await xon.checkPassword('hunter2');\nconsole.log(password.found ? `Exposed ${password.count} times!` : 'Not found in breaches.');\n```\n\n## API Reference\n\n### Constructor\n\n```typescript\nconst xon = new XposedOrNot(config?: XposedOrNotConfig);\n```\n\n#### Configuration Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `apiKey` | `string` | - | API key from [console.xposedornot.com](https://console.xposedornot.com) for Plus API access |\n| `baseUrl` | `string` | `'https://api.xposedornot.com'` | API base URL |\n| `timeout` | `number` | `30000` | Request timeout in milliseconds |\n| `retries` | `number` | `3` | Number of retries after a failed request |\n| `headers` | `Record` | `{}` | Custom headers for all requests |\n\n### Methods\n\n#### `checkEmail(email, options?)`\n\nCheck if an email address has been exposed in any data breaches.\n\n```typescript\nconst result = await xon.checkEmail('user@example.com');\n\n// Result type:\n// {\n// email: string;\n// found: boolean;\n// breaches: string[];\n// }\n```\n\n**Options:**\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `includeDetails` | `boolean` | Include detailed breach information (free API only) |\n\nWhen the client is configured with an `apiKey`, this method automatically uses the\nPlus API and additionally populates `result.details` with rich per-breach objects\n(`BreachInfo[]`: breach date, exposed record count, password risk, and more).\n\n#### `checkPassword(password)`\n\nCheck if a password has been exposed in data breaches, using k-anonymity.\n\n**SECURITY:** Your password is NEVER sent over the network. It is hashed locally\nwith Keccak-512 and only the first 10 characters of the hash are sent to the API,\nso your actual password never leaves your machine.\n\n```typescript\nconst result = await xon.checkPassword('hunter2');\n\n// Result type:\n// {\n// anon: string; // hash prefix that was sent\n// found: boolean;\n// count: number; // times seen in breaches\n// characteristics: { // null if not found\n// digits: number;\n// alphabets: number;\n// special: number;\n// length: number;\n// } | null;\n// }\n\nif (result.found) {\n console.log(`Exposed ${result.count} times - do not use this password!`);\n}\n```\n\n#### `getBreaches(options?)`\n\nGet a list of all known data breaches.\n\n```typescript\n// Get all breaches\nconst breaches = await xon.getBreaches();\n\n// Filter by domain\nconst adobeBreaches = await xon.getBreaches({ domain: 'adobe.com' });\n\n// Get specific breach by ID\nconst linkedIn = await xon.getBreaches({ breachId: 'linkedin' });\n```\n\n**Options:**\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `domain` | `string` | Filter breaches by domain |\n| `breachId` | `string` | Get a specific breach by ID |\n\n**Returns:** Array of `Breach` objects with properties:\n- `breachID` - Unique identifier\n- `breachedDate` - Date of the breach\n- `domain` - Associated domain\n- `industry` - Industry category\n- `exposedData` - Types of data exposed\n- `exposedRecords` - Number of records exposed\n- `verified` - Whether the breach is verified\n- And more...\n\n#### `getBreachAnalytics(email, options?)`\n\nGet detailed breach analytics for an email address.\n\n```typescript\nconst result = await xon.getBreachAnalytics('user@example.com');\n\nif (result.found && result.analytics) {\n console.log('Exposed breaches:', result.analytics.ExposedBreaches);\n console.log('Breach summary:', result.analytics.BreachesSummary);\n console.log('Breach metrics:', result.analytics.BreachMetrics);\n console.log('Paste exposures:', result.analytics.ExposedPastes);\n}\n```\n\n**Options:**\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `token` | `string` | Token for accessing sensitive data |\n\n#### `getDomainBreaches()`\n\nGet breach information for domains verified against your API key. Requires an\n`apiKey` with verified domains configured at\n[console.xposedornot.com](https://console.xposedornot.com); throws\n`AuthenticationError` otherwise.\n\n```typescript\nconst xon = new XposedOrNot({ apiKey: process.env.XON_API_KEY });\nconst result = await xon.getDomainBreaches();\n\nconsole.log(`Exposed records: ${result.breachesDetails.length}`);\nfor (const record of result.breachesDetails) {\n console.log(` ${record.email} - ${record.breach}`);\n}\n\n// Also available: result.yearlyMetrics, result.domainSummary,\n// result.breachSummary, result.top10Breaches, result.detailedBreachInfo\n```\n\n## Plus API (API Key)\n\nThe free API works without any configuration. For detailed breach data, higher\nrate limits, and domain monitoring, get an API key at\n[console.xposedornot.com](https://console.xposedornot.com) and pass it to the\nclient:\n\n```typescript\nconst xon = new XposedOrNot({ apiKey: process.env.XON_API_KEY });\n\n// checkEmail now returns detailed breach info via the Plus API\nconst result = await xon.checkEmail('user@example.com');\nresult.details?.forEach(breach => {\n console.log(`${breach.breach_id}: ${breach.xposed_records} records (${breach.password_risk})`);\n});\n\n// Domain monitoring becomes available\nconst domains = await xon.getDomainBreaches();\n```\n\nCommercial plans are available at [plus.xposedornot.com](https://plus.xposedornot.com/products/api).\n\n## Error Handling\n\nThe library provides custom error classes for different scenarios:\n\n```typescript\nimport {\n XposedOrNot,\n XposedOrNotError,\n RateLimitError,\n ValidationError,\n NetworkError,\n TimeoutError,\n} from 'xposedornot';\n\nconst xon = new XposedOrNot();\n\ntry {\n const result = await xon.checkEmail('invalid-email');\n} catch (error) {\n if (error instanceof ValidationError) {\n console.error('Invalid input:', error.message);\n } else if (error instanceof RateLimitError) {\n console.error('Rate limited. Retry after:', error.retryAfter);\n } else if (error instanceof NetworkError) {\n console.error('Network error:', error.message);\n } else if (error instanceof TimeoutError) {\n console.error('Request timed out');\n } else if (error instanceof XposedOrNotError) {\n console.error('API error:', error.message, error.code);\n }\n}\n```\n\n### Error Types\n\n| Error Class | Description |\n|-------------|-------------|\n| `XposedOrNotError` | Base error class |\n| `ValidationError` | Invalid input (e.g., malformed email) |\n| `RateLimitError` | API rate limit exceeded |\n| `NotFoundError` | Resource not found |\n| `AuthenticationError` | Authentication failed |\n| `NetworkError` | Network connectivity issues |\n| `TimeoutError` | Request timed out |\n| `ServerError` | Server error (5xx) |\n| `ApiError` | General API error |\n\n## Rate Limits\n\nThe free XposedOrNot API is limited to 1 request per second, plus hourly and\ndaily limits. The client automatically spaces free-API requests at least one\nsecond apart and retries rate-limited requests with exponential backoff.\n\nWhen an `apiKey` is configured, client-side spacing is disabled - Plus API\ntier-based limits are enforced server-side. For higher rate limits, commercial\nplans are available at [plus.xposedornot.com](https://plus.xposedornot.com/products/api).\n\n## TypeScript Support\n\nThis library is written in TypeScript and includes full type definitions:\n\n```typescript\nimport type {\n Breach,\n BreachInfo,\n CheckEmailResult,\n BreachAnalyticsResult,\n PasswordCheckResult,\n DomainBreachesResult,\n XposedOrNotConfig,\n} from 'xposedornot';\n```\n\n## CommonJS Usage\n\n```javascript\nconst { XposedOrNot } = require('xposedornot');\n\nconst xon = new XposedOrNot();\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/XposedOrNot/XposedOrNot-JS.git\ncd XposedOrNot-JS\n\n# Install dependencies\nnpm install\n\n# Run tests\nnpm run test:run\n\n# Build\nnpm run build\n\n# Lint\nnpm run lint\n```\n\n## Projects Using This\n\n\n\n> Using `xposedornot` in your project? [Let us know!](https://github.com/XposedOrNot/XposedOrNot-JS/issues/new)\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/XposedOrNot/XposedOrNot-JS/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/XposedOrNot/XposedOrNot-JS/discussions)\n- **API Status**: [XposedOrNot Status](https://xposedornot.com)\n\n## Show Your Support\n\nIf you find this package useful, give it a ⭐ on [GitHub](https://github.com/XposedOrNot/XposedOrNot-JS)!\n\n## License\n\nMIT - see the [LICENSE](LICENSE) file for details.\n\n## Links\n\n- [XposedOrNot Website](https://xposedornot.com)\n- [API Documentation](https://xposedornot.com/api_doc)\n- [npm Package](https://www.npmjs.com/package/xposedornot)\n- [GitHub Repository](https://github.com/XposedOrNot/XposedOrNot-JS)\n- [XposedOrNot API Repository](https://github.com/XposedOrNot/XposedOrNot-API)\n\n---\n\n

\n Made with ❤️ by XposedOrNot\n

\n","readmeFilename":"README.md"}