@phonecheck/phone-number-validator-js 1.7.3-beta.1 → 2.0.0-beta.1

package/README.md

@@ -1,426 +1,420 @@
-# Phone Number information lookup, validation,  carrier name, geo and timezone infos
+# Advanced Phone Number Validator
 
 [![NPM version](https://badgen.net/npm/v/@phonecheck/phone-number-validator-js)](https://npm.im/@phonecheck/phone-number-validator-js)
 [![Build Status](https://github.com/phone-check-app/phone-number-validator-js/workflows/CI/badge.svg)](https://github.com/phone-check-app/phone-number-validator-js/actions)
 [![Downloads](https://img.shields.io/npm/dm/@phonecheck/phone-number-validator-js.svg)](https://www.npmjs.com/package/@phonecheck/phone-number-validator-js)
 [![UNPKG](https://img.shields.io/badge/UNPKG-OK-179BD7.svg)](https://unpkg.com/browse/@phonecheck/phone-number-validator-js@latest/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+
+🚀 **Validate, parse, and enrich international phone numbers** — geocoding,
+carrier lookup, timezone resolution, and number-type detection. Built on
+[Google libphonenumber](https://github.com/google/libphonenumber)'s metadata,
+distributed as compact BSON tables, served from sync (Node) and async (edge /
+serverless) APIs, with first-class adapters for **AWS Lambda, Vercel,
+Cloudflare Workers, GCP Cloud Functions, Netlify, and Azure Functions**.
+
+## 📋 Table of Contents
+
+- [Features](#features)
+- [Use Cases](#use-cases)
+- [API / Cloud Service](#api--cloud-hosted-service)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+- [Examples](#examples)
+- [Command-line Tool (`phone-validate`)](#command-line-tool-phone-validate)
+- [Cache Management](#cache-management)
+- [Custom Resource Loaders](#custom-resource-loaders)
+- [Serverless Usage](#serverless-usage)
+- [Performance](#performance)
+- [Testing](#testing)
+- [Architecture](#architecture)
+- [Contributing](#contributing)
+- [Documentation index](#documentation-index)
 
-### Verify phone number, validate format, checking carrier name, geo and timezone infos.
+## Features
 
-> This library includes phone number lookup and validation, and the geocoding, carrier mapping and timezone mapping functionalities that are available in some of googles [libphonenumber](https://github.com/google/libphonenumber) libraries.
-> 
-> To reduce the amount of data that needs to be loaded to geocode / carrier map a phone-number for each mapping only the relevant number prefixes are loaded from a binary json file (BSON).
- When the prefix could not be found in the provided locale the library tries to fall back to `en` as locale.
-> 
-> The library supports Node.js only at the moment.
+- ✅ **E.164 / national / international parsing** via libphonenumber-js (re-exported)
+- ✅ **Geocoder** — city / region in 30+ locales with English fallback
+- ✅ **Original carrier mapping** — Google's carrier-allocation tables
+- ✅ **Timezone resolution** — IANA zone IDs from the E.164 number
+- ✅ **Number-type detection** — mobile, fixed-line, VoIP, toll-free, premium…
+- ✅ **Sync + async parity** — `geocoder` for Node, `geocoderAsync` for edge / KV
+- ✅ **Pluggable resource loader** — `node:fs`, `fetch`, Cloudflare KV, or your own
+- ✅ **High-performance LRU cache** for deserialized BSON tables
+- ✅ **Six platform adapters** — AWS / Vercel / Cloudflare / GCP / Netlify / Azure
+- ✅ **`phone-validate` CLI** — single-shot validation + JSON logging
+- ✅ **Strict TypeScript** — zero `any` and zero non-null assertions in `src/`
+
+## Use Cases
+
+- Reduce SMS bounce rate by filtering invalid numbers before send
+- Geo-route inbound calls or messages to the right region / carrier
+- Detect VoIP / toll-free / premium-rate numbers in fraud screens
+- Normalize numbers to E.164 for storage and analytics
+- Protect signup / checkout forms from fake numbers and bots
+- Embed validation in mobile, web, and back-office workflows
 
+## API / Cloud Hosted Service
 
-## Features
-✅ Check phone number validity
+We offer this — and more advanced features — as a scalable cloud API:
+[**Phone Number Verification**](https://phone-check.app/products/phone).
 
-✅ Check phone number format
+---
 
-✅ Check phone number carrier name
+## Installation
 
-✅ Check phone number geolocation (city)
+```bash
+bun add @phonecheck/phone-number-validator-js
+# or
+npm install @phonecheck/phone-number-validator-js
+# or
+pnpm add @phonecheck/phone-number-validator-js
+```
 
-✅ Check phone number timezone
+### Requirements (consumers)
+- Node.js >= 22 (Maintenance LTS) — the published bundle is plain Node.js + ESM/CJS
+- TypeScript >= 4.0 (for TypeScript users)
 
-✅ Check phone number country code
+### Requirements (contributing)
+- Bun >= 1.3 (test runner, package manager, dev tooling)
+- Node.js >= 24 only needed for `semantic-release` during the publish step
 
-✅ High-performance LRU caching with configurable size
+### Build System
+- Rollup builds CJS + ESM bundles for the main package and per-platform serverless adapters
+- `bun test` for the unit + isolated suites (no jest, no ts-jest)
+- BSON resource tables (geocodes, carrier mappings, timezones) ship under
+  `resources/` next to the published `dist/`
 
-✅ Comprehensive error handling and input validation
+## Quick Start
 
-✅ TypeScript support with strict type safety
+```typescript
+import {
+  carrier,
+  geocoder,
+  parsePhoneNumberFromString,
+  timezones,
+} from '@phonecheck/phone-number-validator-js';
 
-✅ Serverless architecture support (AWS Lambda, Cloudflare Workers, Vercel Edge, Deno)
+const phone = parsePhoneNumberFromString('+41431234567');
 
+geocoder(phone);            // → "Zurich"
+geocoder(phone, 'de');      // → "Zürich"
+carrier(parsePhoneNumberFromString('01701234567', 'DE'));
+                            // → "T-Mobile"
+timezones(parsePhoneNumberFromString('+12124567890'));
+                            // → ["America/New_York"]
+```
 
-## Use cases
-- Increase delivery rate of SMS campaigns by removing invalid phone numbers
-- Increase SMS open rate and your marketing IPs reputation
-- Protect your website from spam, bots and fake phone numbers
-- Protect your product signup form from fake phone numbers
-- Protect your website forms from fake phone numbers
-- Protect your self from fraud orders and accounts using fake phone numbers
-- Integrate phone number verification into your website forms
-- Integrate phone number verification into your backoffice administration and order processing
-- Integrate phone number verification into your mobile apps
+For a one-shot enrichment call:
 
-## API / Cloud Hosted Service
-We offer this `phone verification and validation and more advanced features` in our Scalable Cloud API Service Offering - You could try it here [Phone Number Verification](https://phone-check.app/products/phone)
+```typescript
+import { enrichPhoneNumber, parsePhoneNumberFromString }
+  from '@phonecheck/phone-number-validator-js';
+
+const phone = parsePhoneNumberFromString('+8619912345678');
+await enrichPhoneNumber(phone, { carrierLocale: 'zh' });
+// {
+//   geocode:   "Hubei",
+//   carrier:   "中国电信",
+//   timezones: ["Asia/Shanghai", ...]
+// }
+```
 
----
+## API Reference
 
-## installation and usage instructions
+### Core Functions
 
-## Installation
+#### `geocoder(phone, locale = 'en'): string | null`
 
-```sh
-npm install @phonecheck/phone-number-validator-js
-```
+Resolve a city / region for the given parsed phone number. Returns `null` for
+landline-only ranges, unknown country codes, or invalid input. Falls back to
+English when the locale-specific table is missing.
 
-or
+#### `carrier(phone, locale = 'en'): string | null`
 
-```sh
-yarn add @phonecheck/phone-number-validator-js
-```
+Resolve the **original** carrier from Google's carrier-allocation tables.
+Note this does **not** reflect ports — see [the upstream FAQ][lpn-carrier].
+Returns `null` for landlines and unmapped ranges.
 
-## Usage
+[lpn-carrier]: https://github.com/google/libphonenumber#mapping-phone-numbers-to-original-carriers
 
-### Core Methods
+#### `timezones(phone): string[] | null`
 
-- `geocoder(phonenumber: PhoneNumber, locale?: GeocoderLocale = 'en'): string | null` - Resolved to the geocode or null if no geocode could be found (e.g. for mobile numbers)
-- `carrier(phonenumber: PhoneNumber, locale?: CarrierLocale = 'en'): string | null` - Resolves to the carrier or null if non could be found (e.g. for fixed line numbers)
-- `timezones(phonenumber: PhoneNumber): Array<string> | null` - Resolved to an array of timezones or null if non where found.
+Resolve one or more IANA timezone IDs for the given E.164 number.
 
-### Cache Management Methods
+#### Async variants
 
-- `clearCache(): void` - Clear all cached data
-- `getCacheSize(): number` - Get current cache size
-- `setCacheSize(size: number): void` - Set maximum cache size (default: 100)
+Same signatures, returning a `Promise`:
 
-## Examples
+- `geocoderAsync(phone, locale?)`
+- `carrierAsync(phone, locale?)`
+- `timezonesAsync(phone)`
+- `enrichPhoneNumber(phone, options?)` — runs all three in parallel
 
-### Basic Usage
+The async variants only require `loader.loadResource`. The sync ones require
+`loader.loadResourceSync`. The bundled `NodeFsResourceLoader` provides both.
 
-```js
-import { geocoder, carrier, timezones, parsePhoneNumberFromString } from '@phonecheck/phone-number-validator-js'
+### Cache
 
-const fixedLineNumber = parsePhoneNumberFromString('+41431234567')
-const locationEN = geocoder(fixedLineNumber) // Zurich
-const locationDE = geocoder(fixedLineNumber, 'de') // Zürich
-const locationIT = geocoder(fixedLineNumber, 'it') // Zurigo
+```typescript
+import {
+  clearCache,
+  DEFAULT_CACHE_SIZE,   // 100
+  getCacheSize,
+  getCacheStats,         // { size, maxSize }
+  setCacheSize,
+} from '@phonecheck/phone-number-validator-js';
+```
 
-const mobileNumber = parsePhoneNumberFromString('+8619912345678')
-const carrierEN = carrier(mobileNumber) // China Telecom
-const carrierZH = carrier(mobileNumber, 'zh') // 中国电信
+The cache stores deserialized BSON tables (one per `country-code/locale`
+pair). Resize for memory-tight environments, clear it for tests / long-running
+workers.
 
-const fixedLineNumber2 = parsePhoneNumberFromString('+49301234567')
-const tzones = timezones(fixedLineNumber2) // ['Europe/Berlin']
-```
+### Resource loaders
 
-### Cache Management
+```typescript
+import { NodeFsResourceLoader, setResourceLoader }
+  from '@phonecheck/phone-number-validator-js';
 
-```js
-import { 
-  clearCache, 
-  getCacheSize, 
-  setCacheSize,
-  geocoder,
-  parsePhoneNumberFromString 
-} from '@phonecheck/phone-number-validator-js'
+setResourceLoader(new NodeFsResourceLoader({ resourcesDir: '/custom/path' }));
+```
 
-// Adjust cache size based on your needs
-setCacheSize(50) // Limit to 50 entries
+The Node entry installs a default loader pointing at the bundled `resources/`.
+Swap it for serverless / edge — see [Custom Resource Loaders](#custom-resource-loaders).
 
-// Monitor cache usage
-console.log(`Cache size: ${getCacheSize()}`)
+### Re-exports
 
-// Perform lookups
-const phoneNumber = parsePhoneNumberFromString('+41431234567')
-const location = geocoder(phoneNumber)
+Everything from `libphonenumber-js` is re-exported under the same name —
+`parsePhoneNumberFromString`, `parsePhoneNumberWithError`, `PhoneNumber`,
+`CountryCode`, formatters, etc. One import covers parsing + enrichment.
 
-// Clear cache when needed
-if (getCacheSize() > 40) {
-  clearCache()
-}
+### Locale types
+
+`GeocoderLocale` and `CarrierLocale` are union types listing the supported
+locales (auto-generated by `scripts/prepare-metadata.ts`). Use them for
+exhaustive switches:
 
-// For long-running processes, you might want to clear cache periodically
-setInterval(() => {
-  clearCache()
-}, 3600000) // Clear every hour
+```typescript
+import type { GeocoderLocale } from '@phonecheck/phone-number-validator-js';
 ```
 
-### Error Handling
+## Examples
 
-```js
-import { geocoder, parsePhoneNumberFromString } from '@phonecheck/phone-number-validator-js'
+### Detecting number type
 
-// Invalid phone numbers return null
-const invalid = parsePhoneNumberFromString('invalid')
-const result = geocoder(invalid) // null
+```typescript
+import { parsePhoneNumberFromString } from '@phonecheck/phone-number-validator-js';
 
-// Undefined/null inputs are handled gracefully
-const result2 = geocoder(undefined) // null
-const result3 = geocoder(null) // null
+const phone = parsePhoneNumberFromString('+14155552671');
+phone?.getType();   // 'FIXED_LINE_OR_MOBILE'
 ```
 
-### TypeScript Usage
+### Validating + formatting in one pass
 
 ```typescript
-import { 
-  geocoder, 
-  carrier, 
-  timezones,
-  parsePhoneNumberFromString,
-  PhoneNumber,
-  GeocoderLocale,
-  CarrierLocale
-} from '@phonecheck/phone-number-validator-js'
+import { parsePhoneNumberFromString } from '@phonecheck/phone-number-validator-js';
 
-// Type-safe locale usage
-const phoneNumber: PhoneNumber | undefined = parsePhoneNumberFromString('+41431234567')
-const locale: GeocoderLocale = 'de'
+function normalize(input: string): string | null {
+  const phone = parsePhoneNumberFromString(input, 'US');
+  if (!phone?.isValid()) return null;
+  return phone.format('E.164');
+}
+
+normalize('(415) 555-2671');   // '+14155552671'
+normalize('not a number');     // null
+```
 
-const location: string | null = geocoder(phoneNumber, locale)
-const carrierInfo: string | null = carrier(phoneNumber)
-const tzs: string[] | null = timezones(phoneNumber)
+### Iterating with locale fallback
 
-// Cache management with types
-import { setCacheSize, getCacheSize, clearCache } from '@phonecheck/phone-number-validator-js'
+```typescript
+import { geocoder, parsePhoneNumberFromString }
+  from '@phonecheck/phone-number-validator-js';
 
-const size: number = getCacheSize()
-setCacheSize(50)
-clearCache()
+const numbers = ['+41431234567', '+8619912345678', '+12124567890'];
+for (const n of numbers) {
+  console.log(n, '→', geocoder(parsePhoneNumberFromString(n), 'de'));
+}
+// +41431234567   → Zürich            (de table)
+// +8619912345678 → Hubei             (en fallback — no de carrier table for 86)
+// +12124567890   → New York          (en fallback)
 ```
 
-## Serverless Support
+## Command-line Tool (`phone-validate`)
 
-The library provides a lightweight serverless version that's optimized for edge environments like AWS Lambda, Cloudflare Workers, Vercel Edge Functions, and Deno Deploy.
+Installing the package globally exposes a `phone-validate` binary:
 
-### Features
-- **244KB bundle size** (minified) - fits well under most size limits
-- **No Node.js dependencies** - runs in any JavaScript environment
-- **Resource loader pattern** - load data from your preferred storage (S3, R2, KV, etc.)
-- **Same API** - drop-in replacement for the standard version
+```bash
+$ bun add -g @phonecheck/phone-number-validator-js
+$ phone-validate +14155552671
+```
 
-### Installation for Serverless
+```text
+✓ VALID    +14155552671
 
-```js
-// Use the serverless entry point
-import { 
-  setResourceLoader,
-  parsePhoneNumber,
-  geocoder,
-  carrier,
-  timezones
-} from '@phonecheck/phone-number-validator-js/serverless'
-```
+Summary
+  country:      US (+1)
+  type:         FIXED_LINE_OR_MOBILE
 
-### Serverless Examples
-
-#### AWS Lambda
-```js
-import { S3Client, GetObjectCommand } from '@aws-sdk/client-s3'
-import { setResourceLoader, geocoder, parsePhoneNumber } from '@phonecheck/phone-number-validator-js/serverless'
-
-const s3 = new S3Client()
-
-// Set up resource loader
-setResourceLoader({
-  async loadResource(path) {
-    try {
-      const command = new GetObjectCommand({
-        Bucket: process.env.RESOURCES_BUCKET,
-        Key: `phone-validator/${path}`
-      })
-      const response = await s3.send(command)
-      return new Uint8Array(await response.Body.transformToByteArray())
-    } catch {
-      return null
-    }
-  }
-})
-
-// Lambda handler
-export async function handler(event) {
-  const phoneNumber = parsePhoneNumber(event.phone, event.country)
-  const location = await geocoder(phoneNumber)
-  
-  return {
-    statusCode: 200,
-    body: JSON.stringify({ location })
-  }
-}
+Formatted
+  E.164:        +14155552671
+  national:     (415) 555-2671
+  international: +1 415 555 2671
+  RFC3966:      tel:+14155552671
+
+Enrichment
+  geocode:      San Francisco
+  timezones:    America/Los_Angeles
 ```
 
-#### Cloudflare Workers
-```js
-import { setResourceLoader, carrier, parsePhoneNumber } from '@phonecheck/phone-number-validator-js/serverless'
-
-// Use R2 storage for resources
-setResourceLoader({
-  async loadResource(path) {
-    const object = await env.RESOURCES_BUCKET.get(`phone-validator/${path}`)
-    if (!object) return null
-    const buffer = await object.arrayBuffer()
-    return new Uint8Array(buffer)
-  }
-})
-
-export default {
-  async fetch(request, env) {
-    const url = new URL(request.url)
-    const phone = url.searchParams.get('phone')
-    
-    const phoneNumber = parsePhoneNumber(phone)
-    const carrierInfo = await carrier(phoneNumber)
-    
-    return Response.json({ carrier: carrierInfo })
-  }
-}
+Output formats:
+
+```bash
+phone-validate +14155552671 --format json --quiet --no-log-file | jq
+phone-validate "(415) 555-2671" --country US --format text
 ```
 
-#### Vercel Edge Functions
-```js
-import { setResourceLoader, timezones, parsePhoneNumber } from '@phonecheck/phone-number-validator-js/serverless'
-
-// Use Vercel Blob storage
-setResourceLoader({
-  async loadResource(path) {
-    const response = await fetch(`${process.env.BLOB_URL}/phone-validator/${path}`)
-    if (!response.ok) return null
-    const buffer = await response.arrayBuffer()
-    return new Uint8Array(buffer)
-  }
-})
+Exit codes: `0` valid, `1` invalid / unparseable, `2` bad CLI args.
 
-export const config = { runtime: 'edge' }
+Run `phone-validate --help` for the full flag list.
 
-export default async function handler(req) {
-  const { phone } = await req.json()
-  const phoneNumber = parsePhoneNumber(phone)
-  const tzs = await timezones(phoneNumber)
-  
-  return Response.json({ timezones: tzs })
-}
+## Cache Management
+
+```typescript
+import {
+  clearCache,
+  getCacheStats,
+  setCacheSize,
+} from '@phonecheck/phone-number-validator-js';
+
+setCacheSize(500);    // default 100
+getCacheStats();      // { size: 17, maxSize: 500 }
+clearCache();         // drop all entries
 ```
 
-### Resource Files
+The cache is keyed by the loader path (`geocodes/en/41.bson`, …) so a single
+process shares hits across the Node entry and any serverless adapter that
+also runs in it.
 
-The serverless version requires resource files to be deployed separately. Download them from the npm package:
+## Custom Resource Loaders
 
-```bash
-# Extract resource files from the npm package
-npm pack @phonecheck/phone-number-validator-js
-tar -xf phonecheck-phone-number-validator-js-*.tgz
-cp -r package/resources/* your-storage-location/
-```
+Implement `ResourceLoader` to host the BSON tables anywhere — KV, R2, S3, a
+public CDN, an in-memory map. The loader is the only thing that changes
+between runtimes; the resolver is the same.
 
-Then upload to your preferred storage (S3, R2, Blob storage, etc.) and configure the resource loader accordingly.
-
-### Performance Tips
-
-1. **Use caching**: The library includes built-in LRU caching
-2. **Deploy resources to the same region** as your functions for lower latency
-3. **Consider using CDN** for resource files if serving globally
-4. **Use sync loader** when possible for better performance:
-
-```js
-// Sync loader for environments that support it
-setResourceLoader({
-  loadResourceSync(path) {
-    // Synchronous loading implementation
-    return loadFromCacheSync(path)
-  },
-  async loadResource(path) {
-    // Async fallback
-    return loadFromCacheAsync(path)
+```typescript
+import {
+  setResourceLoader,
+  type ResourceLoader,
+} from '@phonecheck/phone-number-validator-js/serverless';
+
+class S3Loader implements ResourceLoader {
+  async loadResource(path: string): Promise<Uint8Array | null> {
+    const res = await fetch(`https://my-bucket.s3.amazonaws.com/phone/${path}`);
+    if (res.status === 404) return null;
+    if (!res.ok) throw new Error(`S3 ${res.status} for ${path}`);
+    return new Uint8Array(await res.arrayBuffer());
   }
-})
+}
+
+setResourceLoader(new S3Loader());
 ```
 
-For detailed serverless deployment guides, see [SERVERLESS.md](./SERVERLESS.md).
+Two implementations ship in the package:
 
+| Loader | Backed by | Sync? | Use when |
+|-|-|-|-|
+| `NodeFsResourceLoader` | `node:fs` | ✓ | Running on Node.js with the bundled `resources/` |
+| `FetchResourceLoader`  | `fetch`  | ✗ | Tables hosted on a CDN / R2 / S3 with public reads |
+| `KvResourceLoader`     | Workers KV-shape | ✗ | Cloudflare KV or any KV-shaped store |
 
-## Performance
+## Serverless Usage
+
+For deployment recipes — wrangler.toml, Vercel routes, lambda zips, GCP
+function entries, Netlify redirects, Azure host.json — see
+**[SERVERLESS.md](./SERVERLESS.md)**.
 
-The library uses [tiny-lru](https://www.npmjs.com/package/tiny-lru) for high-performance caching:
+A minimal Cloudflare Worker:
 
-- **O(1) complexity** for cache operations (get, set, delete)
-- **LRU eviction** when cache reaches the size limit
-- **Configurable cache size** to balance memory usage and performance
-- **<1ms lookups** after initial data load
+```typescript
+// src/worker.ts
+import worker from '@phonecheck/phone-number-validator-js/serverless/cloudflare';
 
-## Building
+// Bind PHONE_RESOURCES (KV) in wrangler.toml. The adapter auto-installs a
+// loader from it.
+export default worker;
+```
 
-Build the library for both standard and serverless environments:
+```toml
+# wrangler.toml
+[[kv_namespaces]]
+binding = "PHONE_RESOURCES"
+id      = "..."
+```
 
 ```bash
-yarn build
+$ curl -X POST https://my.workers.dev/ \
+       -H 'content-type: application/json' \
+       -d '{ "phoneNumber": "+14155552671" }'
+{ "success": true, "data": { "valid": true, ... } }
 ```
 
-This command:
-- Creates optimized bundles for CommonJS and ES modules
-- Generates TypeScript declaration files
-- Builds both standard and serverless versions
+## Performance
+
+- BSON tables are loaded **once per `country-code/locale`** and cached as
+  decoded `Document`s.
+- Default cache size is 100 entries — enough for the top ~50 country codes in
+  English and a fallback locale at the same time.
+- Per-lookup cost after warm-up is a single object access + a `while` loop
+  over the prefix (~2-4 iterations on average).
+- The pure verifier bundle is **~80 KB minified** (libphonenumber-js
+  dominates); Workers-only deployments can shrink further by importing
+  `/serverless/verifier` directly instead of `/serverless`.
 
 ## Testing
 
 ```bash
-yarn test
+bun install
+bun run typecheck
+bun run lint
+bun run test            # unit + isolated, no network, no real fs
+bun run test:integration  # opt-in: requires bundled resources/
 ```
 
-Run tests in production mode (suppresses debug logs):
+The unit suite uses an in-memory `MockResourceLoader` so it's fast (under a
+second) and deterministic. The isolated suite exercises the bundled
+`NodeFsResourceLoader` against the real `resources/` directory.
 
-```bash
-NODE_ENV=production yarn test
-```
+For the full test layout, run commands, BSON-key conventions, and CI matrix,
+see [TESTING.md](./TESTING.md).
+
+## Architecture
+
+For the module map, request lifecycle, adapter pattern, and how the
+sync/async API parity works, see [ARCHITECTURE.md](./ARCHITECTURE.md).
 
 ## Contributing
-Please feel free to open an issue or create a pull request and fix bugs or add features, All contributions are welcome. Thank you!
-
-## Support
-
-For issues, questions, or commercial licensing:
-
-🐛 [Open an Issue](https://github.com/phone-check-app/phone-number-validator-js/issues)
-📧 [Email Support](mailto:support@phone-check.app)
-📄 [Commercial License](https://phone-check.app/license/phone-number-validator)
-🌐 [Visit phone-check.app](https://phone-check.app)
-
-## LICENSE
-Business Source License 1.1 - see [LICENSE](LICENSE.md) file for details.
-
-### 📝 When Do You Need a Commercial License?
-
-The BSL allows use only for non-production purposes. Here's a comprehensive guide to help you understand when you need a commercial license:
-
-| Use Case | Commercial License Required? | Details |
-|----------|-----------|---------|
-| **Personal & Learning** | | |
-| 🔬 Exploring phone-number-validator-js for research or learning | ✅ **No** | Use freely for educational purposes |
-| 🎨 Personal hobby projects (non-commercial) | ✅ **No** | Build personal tools and experiments |
-| 🧪 Testing and evaluation in development environment | ✅ **No** | Test all features before purchasing |
-| **Development & Prototyping** | | |
-| 💡 Building proof-of-concept applications | ✅ **No** | Create demos and prototypes |
-| 🛠️ Internal tools (not customer-facing) | ✅ **No** | Use for internal development tools |
-| 📚 Open source projects (non-commercial) | ✅ **No** | Contribute to the community |
-| **Commercial & Production Use** | | |
-| 💰 Revenue-generating applications | ❌ **Yes** | Any app that generates income |
-| ☁️ Software as a Service (SaaS) products | ❌ **Yes** | Cloud-based service offerings |
-| 📦 Distributed commercial software | ❌ **Yes** | Software sold to customers |
-| 🏢 Enterprise production systems | ❌ **Yes** | Business-critical applications |
-| 🔄 Forking for commercial purposes | ❌ **Yes** | Creating derivative commercial products |
-| 🏭 Production use in any form | ❌ **Yes** | Live systems serving real users |
-| **Specific Scenarios** | | |
-| 🎓 Student projects and coursework | ✅ **No** | Academic use is encouraged |
-| 🏗️ CI/CD pipelines (for commercial products) | ❌ **Yes** | Part of commercial development |
-| 📱 Phone validation in production APIs | ❌ **Yes** | Production service usage |
-| 🛒 E-commerce checkout validation | ❌ **Yes** | Revenue-related validation |
-| 📱 Mobile apps (free with ads or paid) | ❌ **Yes** | Monetized applications |
-
-### 💡 Quick Decision Guide
-
-Ask yourself these questions:
-1. **Will real users interact with this in production?** → You need a license
-2. **Will this help generate revenue?** → You need a license  
-3. **Is this for learning or testing only?** → No license needed
-4. **Is this an internal prototype or POC?** → No license needed
-
-### 🎯 Why Choose Our Commercial License?
-
-✨ **Unlimited Usage** - Use in all your production applications  
-🚀 **Priority Support** - Direct support from our engineering team  
-🔄 **Regular Updates** - Get the latest features and improvements  
-🛡️ **Legal Protection** - Full commercial rights and warranty  
-🏢 **Enterprise Ready** - Suitable for large-scale deployments
-
-### 📄 Get Your Commercial License
-
-Ready to use phone-number-validator-js in production?
-
-🛍️ **[Purchase a License](https://phone-check.app/license/phone-number-validator)** - Simple pricing, instant activation  
-📧 **[Contact Sales](mailto:sales@phone-check.app?subject=Interested%20in%20phone-number-validator-js%20commercial%20license)** - For enterprise or custom needs
+
+- Read [AGENTS.md](./AGENTS.md) — code style, branching, commit conventions
+- Branch off `develop`; PRs target `develop`
+- `bun run typecheck && bun run test && bun run build` must be clean
+- Conventional Commits drive the release: `feat:`, `fix:`, `perf:` are
+  releasable; `chore:`, `docs:`, `test:` are not
+- Pre-commit hook runs Biome via `lint-staged`; please don't `--no-verify`
+
+## Documentation index
+
+| Doc | What's in it |
+| - | - |
+| [README.md](./README.md) | Public API, quick start, CLI, examples |
+| [ARCHITECTURE.md](./ARCHITECTURE.md) | Module map, data flow, adapter pattern |
+| [SERVERLESS.md](./SERVERLESS.md) | AWS / Vercel / Cloudflare / GCP / Netlify / Azure deployment |
+| [TESTING.md](./TESTING.md) | Test layout, run commands, BSON-key conventions |
+| [AGENTS.md](./AGENTS.md) | Code-style rules, code-pattern conventions |
+| [examples/README.md](./examples/README.md) | Runnable example index |
+| [CHANGELOG.md](./CHANGELOG.md) | Release history (auto-managed) |
+| [LICENSE.md](./LICENSE.md) | License terms |
+
+## License
+
+See [LICENSE.md](./LICENSE.md).