mirror of
https://dev.azure.com/tstanciu94/PhantomMind/_git/Bitip
synced 2025-10-13 01:52:19 +03:00
Merged PR 110: feat: Implement Node BitipClient for GeoIP service integration
feat: Implement BitipClient for GeoIP service integration - Add BitipClient class for interacting with the Bitip GeoIP Service. - Implement methods for health check, version info, IP location lookup, detailed IP location, and batch IP lookup. - Introduce validation for IP addresses with IpValidator utility. - Normalize URLs with UrlNormalizer utility. - Create constants for API keys and routes. - Add TypeScript types for client options, responses, and errors. - Set up ESLint and Prettier configurations for code quality. - Add unit tests for BitipClient and IpValidator. - Configure TypeScript and build settings with tsup. - Set up Vitest for testing framework and coverage reporting.
This commit is contained in:
Tudor Stanciu
parent
d89a57cb9e
commit
dbb821fe92
27
README.md
27
README.md
@ -8,7 +8,8 @@ Bitip is a professional GeoIP lookup service that provides IP geolocation data t
|
|||||||
- **🌐 Web Interface**: Clean, professional web UI with interactive maps
|
- **🌐 Web Interface**: Clean, professional web UI with interactive maps
|
||||||
- **📡 REST API**: Comprehensive API for single and batch IP lookups
|
- **📡 REST API**: Comprehensive API for single and batch IP lookups
|
||||||
- **📦 .NET Client Library**: Official Bitip.Client NuGet package with strongly-typed models and async support
|
- **📦 .NET Client Library**: Official Bitip.Client NuGet package with strongly-typed models and async support
|
||||||
- **<EFBFBD>🗺️ Interactive Maps**: Static preview and interactive map popups using OpenStreetMap/Leaflet
|
- **📦 Node.js Client Library**: Official @flare/bitip-client npm package with TypeScript support and modern API
|
||||||
|
- **🗺️ Interactive Maps**: Static preview and interactive map popups using OpenStreetMap/Leaflet
|
||||||
- **🔐 API Key Authentication**: Secure access with configurable rate limiting
|
- **🔐 API Key Authentication**: Secure access with configurable rate limiting
|
||||||
- **⚡ Performance**: In-memory caching and efficient database access
|
- **⚡ Performance**: In-memory caching and efficient database access
|
||||||
- **📊 Structured Logging**: Optional integration with Seq for advanced logging
|
- **📊 Structured Logging**: Optional integration with Seq for advanced logging
|
||||||
@ -48,9 +49,29 @@ public class MyService
|
|||||||
|
|
||||||
See [src/clients/dotnet/Bitip.Client/README.md](src/clients/dotnet/Bitip.Client/README.md) for complete documentation.
|
See [src/clients/dotnet/Bitip.Client/README.md](src/clients/dotnet/Bitip.Client/README.md) for complete documentation.
|
||||||
|
|
||||||
### Node.js / JavaScript
|
### Node.js / TypeScript
|
||||||
|
|
||||||
Coming soon! In development at [src/clients/node](src/clients/node).
|
Official npm package with full TypeScript support and modern async/await API:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm install @flare/bitip-client
|
||||||
|
```
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { BitipClient } from '@flare/bitip-client';
|
||||||
|
|
||||||
|
// Create client instance
|
||||||
|
const client = new BitipClient({
|
||||||
|
baseUrl: 'https://your-bitip-instance.com',
|
||||||
|
apiKey: 'your-api-key',
|
||||||
|
});
|
||||||
|
|
||||||
|
// Perform IP lookup
|
||||||
|
const location = await client.getIpLocation('8.8.8.8');
|
||||||
|
console.log(location.country); // United States
|
||||||
|
```
|
||||||
|
|
||||||
|
See [src/clients/node/README.md](src/clients/node/README.md) for complete documentation.
|
||||||
|
|
||||||
### Other Languages
|
### Other Languages
|
||||||
|
|
||||||
|
|||||||
@ -1,17 +1,17 @@
|
|||||||
{
|
{
|
||||||
"title": "Bitip - Professional GeoIP Lookup Service",
|
"title": "Bitip - Professional GeoIP Lookup Service",
|
||||||
"subtitle": "Modern GeoIP lookup service with REST API and interactive web interface",
|
"subtitle": "Modern GeoIP lookup service with REST API and interactive web interface",
|
||||||
"lastUpdated": "2025-10-09T16:00:00Z",
|
"lastUpdated": "2025-10-12T10:00:00Z",
|
||||||
"sections": [
|
"sections": [
|
||||||
{
|
{
|
||||||
"title": "Overview",
|
"title": "Overview",
|
||||||
"content": "Bitip is a high-performance GeoIP lookup service designed to provide accurate geolocation data for IP addresses. Built with modern web technologies, it offers both a RESTful API for programmatic access and an intuitive web interface for interactive lookups. The service uses MaxMind GeoLite2-City and GeoLite2-ASN databases to provide comprehensive IP geolocation with detailed information including country, continent, region, city, coordinates, timezone, postal codes, EU membership status, ISP organization, and autonomous system numbers (ASN). Official client libraries are available for .NET developers via the Bitip.Client NuGet package."
|
"content": "Bitip is a high-performance GeoIP lookup service designed to provide accurate geolocation data for IP addresses. Built with modern web technologies, it offers both a RESTful API for programmatic access and an intuitive web interface for interactive lookups. The service uses MaxMind GeoLite2-City and GeoLite2-ASN databases to provide comprehensive IP geolocation with detailed information including country, continent, region, city, coordinates, timezone, postal codes, EU membership status, ISP organization, and autonomous system numbers (ASN). Official client libraries are available for .NET developers via the Bitip.Client NuGet package and for Node.js/TypeScript developers via the @flare/bitip-client npm package."
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"title": "Client Libraries",
|
"title": "Client Libraries",
|
||||||
"items": [
|
"items": [
|
||||||
"**.NET / C# - Bitip.Client** - Official NuGet package with strongly-typed models, async/await support, and dependency injection integration. Includes comprehensive IntelliSense documentation and 40 unit/integration tests for reliability.",
|
"**.NET / C# - Bitip.Client** - Official NuGet package with strongly-typed models, async/await support, and dependency injection integration. Includes comprehensive IntelliSense documentation and 40 unit/integration tests for reliability.",
|
||||||
"**Node.js / JavaScript** - Client library in development, coming soon",
|
"**Node.js / TypeScript - @flare/bitip-client** - Official npm package with full TypeScript support, dual module format (CommonJS + ESM), and modern async/await API. Includes IP validation, request cancellation, and 33 comprehensive tests for reliability.",
|
||||||
"**REST API** - Direct HTTP access available for any programming language with full OpenAPI/Swagger documentation"
|
"**REST API** - Direct HTTP access available for any programming language with full OpenAPI/Swagger documentation"
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
|
|||||||
@ -1,5 +1,75 @@
|
|||||||
{
|
{
|
||||||
"releases": [
|
"releases": [
|
||||||
|
{
|
||||||
|
"version": "1.1.3",
|
||||||
|
"date": "2025-10-12T10:00:00Z",
|
||||||
|
"title": "IP Validation Improvements & Node.js Client Library",
|
||||||
|
"summary": "Replaced custom regex-based IP validation with Node.js built-in net.isIP() for improved accuracy and IPv6 support. Released official @flare/bitip-client npm package (v1.0.0) for TypeScript/Node.js developers.",
|
||||||
|
"sections": [
|
||||||
|
{
|
||||||
|
"title": "Overview",
|
||||||
|
"content": "Version 1.1.3 improves IP validation reliability by adopting Node.js built-in net.isIP() function, which provides comprehensive IPv4 and IPv6 validation including compressed formats. Additionally, this release introduces the official @flare/bitip-client npm package, bringing first-class TypeScript/Node.js support to complement the existing .NET client library."
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"title": "IP Validation Improvements",
|
||||||
|
"items": [
|
||||||
|
"**Node.js Built-in Validation** - Replaced complex regex patterns with net.isIP() function",
|
||||||
|
"**Enhanced IPv6 Support** - Now validates all IPv6 formats including compressed (::1, fe80::1), standard, and IPv4-mapped addresses",
|
||||||
|
"**Backend & Client Sync** - Consistent validation logic across backend service and Node.js client library",
|
||||||
|
"**Improved Accuracy** - Leverages battle-tested C++ binding from Node.js core for maximum reliability",
|
||||||
|
"**Smaller Bundle Size** - Node.js client reduced from 8.87 KB to 8.15 KB (-8%) by removing regex code",
|
||||||
|
"**Zero Dependencies** - Uses Node.js built-in module, no external packages required"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"title": "Node.js Client Library (@flare/bitip-client v1.0.0)",
|
||||||
|
"items": [
|
||||||
|
"**Official npm Package** - Published to @flare scope on custom npm registry",
|
||||||
|
"**TypeScript First** - Full type definitions and IntelliSense support",
|
||||||
|
"**Dual Module Format** - CommonJS and ESM exports for maximum compatibility",
|
||||||
|
"**Async/Await API** - Modern promise-based interface with AbortSignal cancellation",
|
||||||
|
"**Comprehensive Testing** - 33 passing tests with 100% coverage of core functionality",
|
||||||
|
"**Professional Documentation** - README with installation guide, usage examples, and API reference",
|
||||||
|
"**Minimal Dependencies** - Only requires axios for HTTP requests",
|
||||||
|
"**Tree-shakeable** - Optimized bundle with dead code elimination"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"title": "Node.js Client Features",
|
||||||
|
"items": [
|
||||||
|
"**BitipClient Class** - Clean object-oriented API for all endpoints",
|
||||||
|
"**Five Core Methods** - getHealth(), getVersion(), getIpLocation(), getDetailedIpLocation(), getBatchIpLocation()",
|
||||||
|
"**Built-in IP Validation** - Client-side validation using net.isIP() before API calls",
|
||||||
|
"**Error Aggregation** - Batch operations combine client validation errors with API errors",
|
||||||
|
"**Request Cancellation** - Full AbortSignal support for timeout and cancellation scenarios",
|
||||||
|
"**URL Normalization** - Automatic base URL formatting and trailing slash handling",
|
||||||
|
"**Professional Packaging** - Includes LICENSE, CHANGELOG, comprehensive README, and release guide"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"title": "Backend Changes",
|
||||||
|
"items": [
|
||||||
|
"**Updated geoip.ts** - isValidIP() now uses net.isIP() instead of custom regex",
|
||||||
|
"**Enhanced Documentation** - Added JSDoc comments explaining supported IP formats",
|
||||||
|
"**Backward Compatible** - API behavior unchanged, only internal validation improved"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"title": "Installation & Usage",
|
||||||
|
"content": "Install via npm with `npm install @flare/bitip-client`. Import and instantiate the client with your Bitip API base URL and API key. The package exports TypeScript types for all request/response models. See the package README for complete examples and API documentation."
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"title": "Developer Experience",
|
||||||
|
"items": [
|
||||||
|
"**Zero Configuration Complexity** - Simple setup with just base URL and API key",
|
||||||
|
"**IDE Support** - Full autocomplete and type checking in VS Code, WebStorm, etc.",
|
||||||
|
"**Example Code** - Comprehensive examples for all methods in README",
|
||||||
|
"**Vitest Test Suite** - Modern testing setup with coverage reporting",
|
||||||
|
"**ESLint & Prettier** - Code quality tools configured out of the box"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
},
|
||||||
{
|
{
|
||||||
"version": "1.1.2",
|
"version": "1.1.2",
|
||||||
"date": "2025-10-09T16:00:00Z",
|
"date": "2025-10-09T16:00:00Z",
|
||||||
|
|||||||
@ -1,6 +1,6 @@
|
|||||||
{
|
{
|
||||||
"name": "bitip",
|
"name": "bitip",
|
||||||
"version": "1.1.2",
|
"version": "1.1.3",
|
||||||
"description": "Bitip - GeoIP Lookup Service with REST API and Web Interface",
|
"description": "Bitip - GeoIP Lookup Service with REST API and Web Interface",
|
||||||
"type": "module",
|
"type": "module",
|
||||||
"main": "dist/backend/index.js",
|
"main": "dist/backend/index.js",
|
||||||
|
|||||||
@ -1,4 +1,5 @@
|
|||||||
import { Reader, ReaderModel, City, Asn } from '@maxmind/geoip2-node';
|
import { Reader, ReaderModel, City, Asn } from '@maxmind/geoip2-node';
|
||||||
|
import { isIP } from 'net';
|
||||||
import path from 'path';
|
import path from 'path';
|
||||||
import fs from 'fs';
|
import fs from 'fs';
|
||||||
import NodeCache from 'node-cache';
|
import NodeCache from 'node-cache';
|
||||||
@ -152,12 +153,13 @@ class GeoIPService {
|
|||||||
return { succeeded, failed };
|
return { succeeded, failed };
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Validates if a string is a valid IP address (IPv4 or IPv6)
|
||||||
|
* @param ip - IP address string to validate
|
||||||
|
* @returns true if valid IP address, false otherwise
|
||||||
|
*/
|
||||||
isValidIP(ip: string): boolean {
|
isValidIP(ip: string): boolean {
|
||||||
const ipv4Regex =
|
return isIP(ip) !== 0;
|
||||||
/^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$/;
|
|
||||||
const ipv6Regex = /^(?:[0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}$/;
|
|
||||||
|
|
||||||
return ipv4Regex.test(ip) || ipv6Regex.test(ip);
|
|
||||||
}
|
}
|
||||||
|
|
||||||
isPrivateIP(ip: string): boolean {
|
isPrivateIP(ip: string): boolean {
|
||||||
|
|||||||
45
src/clients/node/.gitignore
vendored
Normal file
45
src/clients/node/.gitignore
vendored
Normal file
@ -0,0 +1,45 @@
|
|||||||
|
# Dependencies
|
||||||
|
node_modules/
|
||||||
|
package-lock.json
|
||||||
|
yarn.lock
|
||||||
|
pnpm-lock.yaml
|
||||||
|
|
||||||
|
# Build output
|
||||||
|
dist/
|
||||||
|
build/
|
||||||
|
*.tsbuildinfo
|
||||||
|
|
||||||
|
# Coverage
|
||||||
|
coverage/
|
||||||
|
.nyc_output/
|
||||||
|
|
||||||
|
# IDE
|
||||||
|
.vscode/
|
||||||
|
.idea/
|
||||||
|
*.swp
|
||||||
|
*.swo
|
||||||
|
*~
|
||||||
|
|
||||||
|
# OS
|
||||||
|
.DS_Store
|
||||||
|
Thumbs.db
|
||||||
|
|
||||||
|
# Logs
|
||||||
|
logs/
|
||||||
|
*.log
|
||||||
|
npm-debug.log*
|
||||||
|
yarn-debug.log*
|
||||||
|
yarn-error.log*
|
||||||
|
|
||||||
|
# Environment
|
||||||
|
.env
|
||||||
|
.env.local
|
||||||
|
.env.*.local
|
||||||
|
|
||||||
|
# Testing
|
||||||
|
.vitest/
|
||||||
|
|
||||||
|
# Temporary files
|
||||||
|
*.tmp
|
||||||
|
*.temp
|
||||||
|
.cache/
|
||||||
8
src/clients/node/.npmrc
Normal file
8
src/clients/node/.npmrc
Normal file
@ -0,0 +1,8 @@
|
|||||||
|
//lab.code-rove.com/:_authToken=${OWN_NPM_TOKEN}
|
||||||
|
@flare:registry=https://lab.code-rove.com/public-node-registry
|
||||||
|
|
||||||
|
# Optional: Enable package-lock.json
|
||||||
|
package-lock=true
|
||||||
|
|
||||||
|
# Optional: Engine strict mode
|
||||||
|
engine-strict=true
|
||||||
5
src/clients/node/.prettierignore
Normal file
5
src/clients/node/.prettierignore
Normal file
@ -0,0 +1,5 @@
|
|||||||
|
node_modules
|
||||||
|
dist
|
||||||
|
coverage
|
||||||
|
*.log
|
||||||
|
.DS_Store
|
||||||
48
src/clients/node/CHANGELOG.md
Normal file
48
src/clients/node/CHANGELOG.md
Normal file
@ -0,0 +1,48 @@
|
|||||||
|
# Changelog
|
||||||
|
|
||||||
|
All notable changes to the bitip-client package will be documented in this file.
|
||||||
|
|
||||||
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
||||||
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||||
|
|
||||||
|
## [1.0.0] - 2025-10-12
|
||||||
|
|
||||||
|
### Added
|
||||||
|
|
||||||
|
- Initial release of @flare/bitip-client
|
||||||
|
- `BitipClient` class with full API integration
|
||||||
|
- Simple IP geolocation lookup (`getIpLocation`)
|
||||||
|
- Detailed IP geolocation with ASN information (`getDetailedIpLocation`)
|
||||||
|
- Batch IP lookup functionality (`getBatchIpLocation`)
|
||||||
|
- Health check endpoint (`getHealth`)
|
||||||
|
- Version information retrieval (`getVersion`)
|
||||||
|
- Built-in IP address validation using Node.js `net.isIP()`
|
||||||
|
- URL normalization utilities (`UrlNormalizer`)
|
||||||
|
- Full TypeScript support with type definitions
|
||||||
|
- Comprehensive test suite with Vitest (19 tests)
|
||||||
|
- Request cancellation support via AbortSignal
|
||||||
|
- Professional error handling
|
||||||
|
- CommonJS and ESM module support
|
||||||
|
|
||||||
|
### Features
|
||||||
|
|
||||||
|
- ✅ IPv4 and IPv6 address support
|
||||||
|
- ✅ Client-side IP validation
|
||||||
|
- ✅ Batch processing with separate success/failure tracking
|
||||||
|
- ✅ Automatic URL normalization
|
||||||
|
- ✅ Configurable request timeout
|
||||||
|
- ✅ Full type safety with TypeScript
|
||||||
|
- ✅ Zero runtime dependencies (except axios)
|
||||||
|
- ✅ Modern ES2020+ JavaScript
|
||||||
|
- ✅ Tree-shakeable exports
|
||||||
|
|
||||||
|
### Documentation
|
||||||
|
|
||||||
|
- Comprehensive README with usage examples
|
||||||
|
- API documentation in TypeScript definitions
|
||||||
|
- Release guide for publishing to npm registry
|
||||||
|
- Full test coverage documentation
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Copyright © 2025 Tudor Stanciu**
|
||||||
27
src/clients/node/LICENSE
Normal file
27
src/clients/node/LICENSE
Normal file
@ -0,0 +1,27 @@
|
|||||||
|
MIT License
|
||||||
|
|
||||||
|
Copyright (c) 2025 Tudor Stanciu
|
||||||
|
|
||||||
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||||
|
of this software and associated documentation files (the "Software"), to deal
|
||||||
|
in the Software without restriction, including without limitation the rights
|
||||||
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||||
|
copies of the Software, and to permit persons to whom the Software is
|
||||||
|
furnished to do so, subject to the following conditions:
|
||||||
|
|
||||||
|
The above copyright notice and this permission notice shall be included in all
|
||||||
|
copies or substantial portions of the Software.
|
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||||
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||||
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||||
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||||
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||||
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||||
|
SOFTWARE.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Note: This license applies to the bitip-client library only. Access to the
|
||||||
|
Bitip GeoIP Service API requires a separate API key and is subject to the
|
||||||
|
service's own terms and conditions.
|
||||||
@ -1 +1,414 @@
|
|||||||
# In development
|
# @flare/bitip-client
|
||||||
|
|
||||||
|
A TypeScript/Node.js client library for integrating with the [Bitip GeoIP Service](https://lab.code-rove.com/bitip/). This library provides a simple and efficient way to perform IP geolocation lookups, retrieve health status, and get version information from your Bitip API instance.
|
||||||
|
|
||||||
|
[Bitip](https://lab.code-rove.com/gitea/tudor.stanciu/bitip#readme) is a high-performance GeoIP lookup service designed to provide accurate geolocation data for IP addresses.
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
- ✅ Simple IP geolocation lookup
|
||||||
|
- ✅ Detailed IP geolocation with ASN information
|
||||||
|
- ✅ Batch IP geolocation for multiple addresses
|
||||||
|
- ✅ Health check endpoint
|
||||||
|
- ✅ Version information retrieval
|
||||||
|
- ✅ Built-in IP address validation
|
||||||
|
- ✅ Request cancellation support via AbortSignal
|
||||||
|
- ✅ Full TypeScript support with comprehensive type definitions
|
||||||
|
- ✅ CommonJS and ESM module formats
|
||||||
|
- ✅ Minimal dependencies (only axios for HTTP)
|
||||||
|
- ✅ Professional error handling
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
Install the package via npm:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm install @flare/bitip-client
|
||||||
|
```
|
||||||
|
|
||||||
|
Or via yarn:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
yarn add @flare/bitip-client
|
||||||
|
```
|
||||||
|
|
||||||
|
Or via pnpm:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pnpm add @flare/bitip-client
|
||||||
|
```
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
### Basic Usage
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { BitipClient } from '@flare/bitip-client';
|
||||||
|
|
||||||
|
// Create client instance
|
||||||
|
const client = new BitipClient({
|
||||||
|
baseUrl: 'https://your-bitip-instance.com/api',
|
||||||
|
apiKey: 'your-api-key-here',
|
||||||
|
});
|
||||||
|
|
||||||
|
// Perform IP lookup
|
||||||
|
const location = await client.getIpLocation('8.8.8.8');
|
||||||
|
console.log(location);
|
||||||
|
```
|
||||||
|
|
||||||
|
### With Custom Timeout
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const client = new BitipClient({
|
||||||
|
baseUrl: 'https://your-bitip-instance.com/api',
|
||||||
|
apiKey: 'your-api-key-here',
|
||||||
|
timeout: 10000, // 10 seconds
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Usage Examples
|
||||||
|
|
||||||
|
### Simple IP Lookup
|
||||||
|
|
||||||
|
Get basic geolocation information for an IP address:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const location = await client.getIpLocation('8.8.8.8');
|
||||||
|
|
||||||
|
console.log(`IP: ${location.ip}`);
|
||||||
|
console.log(`Country: ${location.country} (${location.country_code})`);
|
||||||
|
console.log(`City: ${location.city}`);
|
||||||
|
console.log(`Region: ${location.region}`);
|
||||||
|
console.log(`Coordinates: ${location.latitude}, ${location.longitude}`);
|
||||||
|
console.log(`Timezone: ${location.timezone}`);
|
||||||
|
console.log(`EU Member: ${location.is_in_european_union}`);
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response Type (`IpLocation`):**
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
ip: string;
|
||||||
|
country: string;
|
||||||
|
country_code: string;
|
||||||
|
is_in_european_union: boolean;
|
||||||
|
region: string;
|
||||||
|
region_code: string | null;
|
||||||
|
city: string;
|
||||||
|
latitude: number | null;
|
||||||
|
longitude: number | null;
|
||||||
|
timezone: string | null;
|
||||||
|
postal_code: string | null;
|
||||||
|
continent_code: string | null;
|
||||||
|
continent_name: string | null;
|
||||||
|
organization: string | null;
|
||||||
|
asn: number | null;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Detailed IP Lookup
|
||||||
|
|
||||||
|
Get comprehensive geolocation data including ASN information:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const detailedLocation = await client.getDetailedIpLocation('1.1.1.1');
|
||||||
|
|
||||||
|
console.log(`IP: ${detailedLocation.ip}`);
|
||||||
|
console.log(`Country: ${detailedLocation.location.country?.names?.['en']}`);
|
||||||
|
console.log(`City: ${detailedLocation.location.city?.names?.['en']}`);
|
||||||
|
console.log(`Latitude: ${detailedLocation.location.location?.latitude}`);
|
||||||
|
console.log(`Longitude: ${detailedLocation.location.location?.longitude}`);
|
||||||
|
console.log(`Timezone: ${detailedLocation.location.location?.time_zone}`);
|
||||||
|
console.log(`ASN: ${detailedLocation.asn.autonomousSystemNumber}`);
|
||||||
|
console.log(`ISP: ${detailedLocation.asn.autonomousSystemOrganization}`);
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response Type (`DetailedIpLocation`):**
|
||||||
|
|
||||||
|
- `ip` - The queried IP address
|
||||||
|
- `location` - Nested geolocation data
|
||||||
|
- `country` - Country info with ISO code and localized names
|
||||||
|
- `city` - City with localized names
|
||||||
|
- `subdivisions` - State/province information
|
||||||
|
- `location` - Latitude, longitude, timezone
|
||||||
|
- `postal` - Postal code
|
||||||
|
- `continent` - Continent code and names
|
||||||
|
- `registered_country` - Registered country info
|
||||||
|
- `traits` - Proxy and satellite provider flags
|
||||||
|
- `asn` - Autonomous System Number information
|
||||||
|
- `autonomousSystemNumber` - ASN number
|
||||||
|
- `autonomousSystemOrganization` - ISP name
|
||||||
|
- `ipAddress` - IP address
|
||||||
|
- `network` - Network range
|
||||||
|
|
||||||
|
### Batch IP Lookup
|
||||||
|
|
||||||
|
Query multiple IP addresses in a single request. Results are separated into succeeded and failed:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const ips = ['8.8.8.8', 'invalid-ip', '1.1.1.1'];
|
||||||
|
const batchResult = await client.getBatchIpLocation(ips);
|
||||||
|
|
||||||
|
// Process successful lookups
|
||||||
|
for (const location of batchResult.succeeded) {
|
||||||
|
console.log(`${location.ip}: ${location.country} (${location.country_code}), ${location.city}`);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Handle failures
|
||||||
|
for (const error of batchResult.failed) {
|
||||||
|
console.log(`Error for ${error.ip}: ${error.error}`);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response Type (`BatchIpLookupResponse`):**
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
succeeded: IpLocation[]; // Array of successful lookups
|
||||||
|
failed: BatchIpLookupError[]; // Array of failed lookups with error messages
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Note:** Invalid IPs are validated client-side before sending to the API. The API may return additional errors for private IPs or IPs not found in the database.
|
||||||
|
|
||||||
|
### Health Check
|
||||||
|
|
||||||
|
Check the health status of the Bitip API:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const health = await client.getHealth();
|
||||||
|
|
||||||
|
console.log(`Status: ${health.status}`);
|
||||||
|
console.log(`Service: ${health.service}`);
|
||||||
|
console.log(`Timestamp: ${health.timestamp}`);
|
||||||
|
|
||||||
|
if (health.error) {
|
||||||
|
console.log(`Error: ${health.error}`);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Version Information
|
||||||
|
|
||||||
|
Retrieve the API version and build details:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const version = await client.getVersion();
|
||||||
|
|
||||||
|
console.log(`Version: ${version.version}`);
|
||||||
|
console.log(`Commit: ${version.commitHash}`);
|
||||||
|
console.log(`Build Date: ${version.buildDate}`);
|
||||||
|
```
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
The client throws standard JavaScript errors that you should handle appropriately:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
try {
|
||||||
|
const location = await client.getIpLocation('invalid-ip');
|
||||||
|
} catch (error) {
|
||||||
|
if (error instanceof Error) {
|
||||||
|
// Invalid IP format (single lookup methods only)
|
||||||
|
console.error(`Error: ${error.message}`);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Note:** `getBatchIpLocation` does not throw exceptions for invalid IPs. Instead, it returns error results for each invalid IP in the response.
|
||||||
|
|
||||||
|
### Common API Error Responses
|
||||||
|
|
||||||
|
- **400 Bad Request** - Invalid IP address format or private IP (single lookups)
|
||||||
|
- **404 Not Found** - IP address not found in database
|
||||||
|
- **429 Too Many Requests** - Rate limit exceeded
|
||||||
|
- **503 Service Unavailable** - Service under maintenance
|
||||||
|
|
||||||
|
## Request Cancellation
|
||||||
|
|
||||||
|
All methods support `AbortSignal` for request cancellation:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const controller = new AbortController();
|
||||||
|
|
||||||
|
// Set timeout
|
||||||
|
setTimeout(() => controller.abort(), 5000);
|
||||||
|
|
||||||
|
try {
|
||||||
|
const location = await client.getIpLocation('8.8.8.8', controller.signal);
|
||||||
|
} catch (error) {
|
||||||
|
if (error.name === 'AbortError') {
|
||||||
|
console.log('Request cancelled or timed out');
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
### Base URL Format
|
||||||
|
|
||||||
|
The base URL should point to your Bitip API instance. The library automatically ensures proper URL formatting:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// All of these work correctly:
|
||||||
|
new BitipClient({ baseUrl: 'https://bitip.example.com/api', apiKey: 'key' });
|
||||||
|
new BitipClient({ baseUrl: 'https://bitip.example.com/api/', apiKey: 'key' });
|
||||||
|
new BitipClient({ baseUrl: 'https://bitip.example.com', apiKey: 'key' }); // '/api' is added automatically
|
||||||
|
```
|
||||||
|
|
||||||
|
### API Key
|
||||||
|
|
||||||
|
The API key is sent via the `X-API-Key` header in all requests. Make sure your Bitip API is configured to accept your key.
|
||||||
|
|
||||||
|
### Timeout
|
||||||
|
|
||||||
|
Default timeout is 30 seconds. You can customize it:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const client = new BitipClient({
|
||||||
|
baseUrl: 'https://bitip.example.com/api',
|
||||||
|
apiKey: 'your-api-key',
|
||||||
|
timeout: 15000, // 15 seconds
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## API Methods
|
||||||
|
|
||||||
|
| Method | Endpoint | Description |
|
||||||
|
| ------------------------------ | ------------------------------ | --------------------- |
|
||||||
|
| `getHealth(signal?)` | `GET /health` | Health check |
|
||||||
|
| `getVersion(signal?)` | `GET /version` | Version info |
|
||||||
|
| `getIpLocation(ip, signal?)` | `GET /lookup?ip={ip}` | Simple lookup |
|
||||||
|
| `getDetailedIpLocation(ip, signal?)` | `GET /lookup/detailed?ip={ip}` | Detailed lookup |
|
||||||
|
| `getBatchIpLocation(ips, signal?)` | `POST /lookup/batch` | Batch lookup |
|
||||||
|
|
||||||
|
## TypeScript Support
|
||||||
|
|
||||||
|
This library is written in TypeScript and includes comprehensive type definitions:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import type {
|
||||||
|
BitipClientOptions,
|
||||||
|
IpLocation,
|
||||||
|
DetailedIpLocation,
|
||||||
|
BatchIpLookupResponse,
|
||||||
|
HealthInfo,
|
||||||
|
VersionInfo,
|
||||||
|
} from '@flare/bitip-client';
|
||||||
|
```
|
||||||
|
|
||||||
|
## Utilities
|
||||||
|
|
||||||
|
### IP Validator
|
||||||
|
|
||||||
|
Validate IP addresses manually:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { IpValidator } from '@flare/bitip-client';
|
||||||
|
|
||||||
|
// Validate and throw error if invalid
|
||||||
|
IpValidator.validate('8.8.8.8'); // OK
|
||||||
|
IpValidator.validate('invalid-ip'); // Throws error
|
||||||
|
|
||||||
|
// Check validity without throwing
|
||||||
|
if (IpValidator.isValid('8.8.8.8')) {
|
||||||
|
console.log('Valid IP');
|
||||||
|
}
|
||||||
|
|
||||||
|
// Check IP version
|
||||||
|
IpValidator.isIPv4('8.8.8.8'); // true
|
||||||
|
IpValidator.isIPv6('2001:4860:4860::8888'); // true
|
||||||
|
```
|
||||||
|
|
||||||
|
### URL Normalizer
|
||||||
|
|
||||||
|
Normalize URLs:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { UrlNormalizer } from '@flare/bitip-client';
|
||||||
|
|
||||||
|
const url = UrlNormalizer.ensureTrailingSlash('https://example.com', '/api');
|
||||||
|
// Result: "https://example.com/api/"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- **Node.js** 18.0.0 or higher
|
||||||
|
- **axios** ^1.12.2 (installed automatically)
|
||||||
|
|
||||||
|
**Note**: IP validation uses Node.js built-in `net.isIP()` for maximum accuracy and zero dependencies.
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
1. **Reuse client instances** - Create one instance and reuse it across your application
|
||||||
|
2. **Use request cancellation** for requests that may take time
|
||||||
|
3. **Handle errors appropriately** - Network calls can fail
|
||||||
|
4. **Use batch lookups** when querying multiple IPs to reduce API calls
|
||||||
|
5. **Consider caching results** - IP geolocation data doesn't change frequently
|
||||||
|
6. **Validate IPs client-side** - Use the built-in `IpValidator` before making API calls
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
Run the test suite:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm test
|
||||||
|
```
|
||||||
|
|
||||||
|
Run tests with coverage:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run test:coverage
|
||||||
|
```
|
||||||
|
|
||||||
|
Run tests in watch mode:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run test:watch
|
||||||
|
```
|
||||||
|
|
||||||
|
## Building
|
||||||
|
|
||||||
|
Build the library:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run build
|
||||||
|
```
|
||||||
|
|
||||||
|
This generates:
|
||||||
|
|
||||||
|
- `dist/index.js` - CommonJS bundle
|
||||||
|
- `dist/index.mjs` - ESM bundle
|
||||||
|
- `dist/index.d.ts` - TypeScript definitions
|
||||||
|
|
||||||
|
## Publishing
|
||||||
|
|
||||||
|
See [RELEASE.md](RELEASE.md) for detailed instructions on publishing to your npm registry.
|
||||||
|
|
||||||
|
Publish to registry:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run publish:registry
|
||||||
|
```
|
||||||
|
|
||||||
|
Or publish to local Verdaccio for testing:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run publish:local
|
||||||
|
```
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
||||||
|
|
||||||
|
**Note:** This license applies to the @flare/bitip-client library only. Access to the Bitip GeoIP Service API requires a separate API key and is subject to the service's own terms and conditions.
|
||||||
|
|
||||||
|
## Support
|
||||||
|
|
||||||
|
For issues, questions, or contributions, please visit:
|
||||||
|
|
||||||
|
- **Repository**: https://lab.code-rove.com/gitea/tudor.stanciu/bitip
|
||||||
|
- **Bitip Service**: https://lab.code-rove.com/bitip/
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Copyright © 2025 Tudor Stanciu**
|
||||||
|
|||||||
412
src/clients/node/RELEASE.md
Normal file
412
src/clients/node/RELEASE.md
Normal file
@ -0,0 +1,412 @@
|
|||||||
|
# @flare/bitip-client Release Guide
|
||||||
|
|
||||||
|
This guide explains how to publish the @flare/bitip-client npm package to your npm registry.
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
Before publishing, ensure you have:
|
||||||
|
|
||||||
|
1. **Node.js** 18.0.0 or higher installed
|
||||||
|
2. **npm** or **yarn** package manager
|
||||||
|
3. **Access** to your npm registry at `https://lab.code-rove.com/public-node-registry`
|
||||||
|
4. **Authentication token** configured in `.npmrc`
|
||||||
|
|
||||||
|
## Version Management
|
||||||
|
|
||||||
|
### Semantic Versioning
|
||||||
|
|
||||||
|
@flare/bitip-client follows [Semantic Versioning 2.0.0](https://semver.org/):
|
||||||
|
|
||||||
|
```
|
||||||
|
MAJOR.MINOR.PATCH (e.g., 1.0.0)
|
||||||
|
```
|
||||||
|
|
||||||
|
- **MAJOR**: Breaking changes to the API
|
||||||
|
- **MINOR**: New features, backward compatible
|
||||||
|
- **PATCH**: Bug fixes, backward compatible
|
||||||
|
|
||||||
|
### When to Increment
|
||||||
|
|
||||||
|
| Change Type | Version Update | Example |
|
||||||
|
| ------------------------- | ---------------- | ----------------- |
|
||||||
|
| Breaking API changes | MAJOR | `1.0.0` → `2.0.0` |
|
||||||
|
| New methods/features | MINOR | `1.0.0` → `1.1.0` |
|
||||||
|
| Bug fixes | PATCH | `1.0.0` → `1.0.1` |
|
||||||
|
| Documentation only | PATCH (optional) | `1.0.0` → `1.0.1` |
|
||||||
|
|
||||||
|
### How to Update Version
|
||||||
|
|
||||||
|
1. **Edit `package.json`**:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"version": "1.0.0"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Update `CHANGELOG.md`** with changes:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## [1.0.0] - 2025-10-10
|
||||||
|
|
||||||
|
### Added
|
||||||
|
- Initial release
|
||||||
|
- IP geolocation lookup (simple and detailed)
|
||||||
|
- Batch lookup functionality
|
||||||
|
- Health check endpoint
|
||||||
|
- Version information retrieval
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Commit the changes**:
|
||||||
|
```bash
|
||||||
|
git add package.json CHANGELOG.md
|
||||||
|
git commit -m "chore: bump version to 1.0.0"
|
||||||
|
git push
|
||||||
|
```
|
||||||
|
|
||||||
|
## Building the Package
|
||||||
|
|
||||||
|
### 1. Install Dependencies
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd d:\Git\Home\Bitip\src\clients\node
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Run Type Check
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run typecheck
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Run Tests
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm test
|
||||||
|
```
|
||||||
|
|
||||||
|
Ensure all tests pass before building.
|
||||||
|
|
||||||
|
### 4. Build the Package
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run build
|
||||||
|
```
|
||||||
|
|
||||||
|
This creates the `dist/` folder with:
|
||||||
|
- `index.js` - CommonJS bundle
|
||||||
|
- `index.mjs` - ESM bundle
|
||||||
|
- `index.d.ts` - TypeScript type definitions
|
||||||
|
- Source maps for debugging
|
||||||
|
|
||||||
|
### 5. Verify Build Output
|
||||||
|
|
||||||
|
Check that the dist folder contains all necessary files:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ls dist/
|
||||||
|
```
|
||||||
|
|
||||||
|
You should see:
|
||||||
|
- `index.js`
|
||||||
|
- `index.mjs`
|
||||||
|
- `index.d.ts`
|
||||||
|
- `*.map` files
|
||||||
|
|
||||||
|
## Publishing to npm Registry
|
||||||
|
|
||||||
|
### Option 1: Publish to Lab Registry (Recommended)
|
||||||
|
|
||||||
|
The package is configured to publish to `https://lab.code-rove.com/public-node-registry` by default.
|
||||||
|
|
||||||
|
#### Setup Authentication
|
||||||
|
|
||||||
|
Ensure your `.npmrc` file has the authentication token:
|
||||||
|
|
||||||
|
```
|
||||||
|
//lab.code-rove.com/:_authToken=${OWN_NPM_TOKEN}
|
||||||
|
@flare:registry=https://lab.code-rove.com/public-node-registry
|
||||||
|
```
|
||||||
|
|
||||||
|
Set the `OWN_NPM_TOKEN` environment variable or replace `${OWN_NPM_TOKEN}` with your actual token.
|
||||||
|
|
||||||
|
#### Publish Package
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run publish:registry
|
||||||
|
```
|
||||||
|
|
||||||
|
This uses the `publishConfig` in package.json to publish to the correct registry.
|
||||||
|
|
||||||
|
### Option 2: Publish to Local Verdaccio (Testing)
|
||||||
|
|
||||||
|
For local testing, use:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run publish:local
|
||||||
|
```
|
||||||
|
|
||||||
|
This publishes to `http://localhost:4873` (default Verdaccio).
|
||||||
|
|
||||||
|
### Option 3: Manual Publishing
|
||||||
|
|
||||||
|
#### Publish with specific registry
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm publish
|
||||||
|
```
|
||||||
|
|
||||||
|
The registry is configured in `package.json` publishConfig, so this will use the lab registry.
|
||||||
|
|
||||||
|
Or specify explicitly:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm publish --registry https://lab.code-rove.com/public-node-registry
|
||||||
|
```
|
||||||
|
|
||||||
|
### Option 4: Using npm version Command
|
||||||
|
|
||||||
|
Automatically bump version, commit, tag, and publish:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Patch version (1.0.0 -> 1.0.1)
|
||||||
|
npm version patch
|
||||||
|
npm run publish:registry
|
||||||
|
|
||||||
|
# Minor version (1.0.0 -> 1.1.0)
|
||||||
|
npm version minor
|
||||||
|
npm run publish:registry
|
||||||
|
|
||||||
|
# Major version (1.0.0 -> 2.0.0)
|
||||||
|
npm version major
|
||||||
|
npm run publish:registry
|
||||||
|
```
|
||||||
|
|
||||||
|
### Verify Publication
|
||||||
|
|
||||||
|
After publishing, verify the package is available:
|
||||||
|
|
||||||
|
1. **Via npm info**:
|
||||||
|
```bash
|
||||||
|
npm info @flare/bitip-client --registry https://lab.code-rove.com/public-node-registry
|
||||||
|
```
|
||||||
|
2. **Via npm search**:
|
||||||
|
```bash
|
||||||
|
npm search @flare/bitip-client --registry https://lab.code-rove.com/public-node-registry
|
||||||
|
```
|
||||||
|
3. **Via browser**: https://lab.code-rove.com/public-node-registry/@flare/bitip-client
|
||||||
|
|
||||||
|
## Complete Release Workflow
|
||||||
|
|
||||||
|
Here's the full workflow from start to finish:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Navigate to project directory
|
||||||
|
cd d:\Git\Home\Bitip\src\clients\node
|
||||||
|
|
||||||
|
# 2. Update version in package.json (manually edit)
|
||||||
|
# 3. Update CHANGELOG.md (manually edit)
|
||||||
|
|
||||||
|
# 4. Install dependencies (if not already done)
|
||||||
|
npm install
|
||||||
|
|
||||||
|
# 5. Run type checking
|
||||||
|
npm run typecheck
|
||||||
|
|
||||||
|
# 6. Run tests
|
||||||
|
npm test
|
||||||
|
|
||||||
|
# 7. Run test coverage
|
||||||
|
npm run test:coverage
|
||||||
|
|
||||||
|
# 8. Build the package
|
||||||
|
npm run build
|
||||||
|
|
||||||
|
# 9. Commit version changes
|
||||||
|
git add package.json CHANGELOG.md
|
||||||
|
git commit -m "chore: release version 1.0.0"
|
||||||
|
|
||||||
|
# 10. Create git tag
|
||||||
|
git tag -a v1.0.0 -m "Release version 1.0.0"
|
||||||
|
|
||||||
|
# 11. Publish to npm registry
|
||||||
|
npm run publish:registry
|
||||||
|
|
||||||
|
# 12. Push git changes and tags
|
||||||
|
git push
|
||||||
|
git push --tags
|
||||||
|
```
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Package Already Exists
|
||||||
|
|
||||||
|
If you get "Cannot publish over existing version" error:
|
||||||
|
|
||||||
|
- **Solution 1**: Increment the version number (most common)
|
||||||
|
- **Solution 2**: Unpublish the old version (if you have permissions)
|
||||||
|
```bash
|
||||||
|
npm unpublish @flare/bitip-client@1.0.0 --registry https://lab.code-rove.com/public-node-registry
|
||||||
|
```
|
||||||
|
|
||||||
|
### Authentication Failed
|
||||||
|
|
||||||
|
```
|
||||||
|
npm ERR! 401 Unauthorized
|
||||||
|
```
|
||||||
|
|
||||||
|
**Solutions**:
|
||||||
|
|
||||||
|
- Check your `.npmrc` file has the correct token
|
||||||
|
- Verify the `OWN_NPM_TOKEN` environment variable is set
|
||||||
|
- Ensure you have publish permissions on the registry
|
||||||
|
- Check token hasn't expired
|
||||||
|
|
||||||
|
### Build Errors
|
||||||
|
|
||||||
|
If build fails:
|
||||||
|
|
||||||
|
- Check TypeScript errors: `npm run typecheck`
|
||||||
|
- Ensure all dependencies are installed: `npm install`
|
||||||
|
- Clear cache: `rm -rf node_modules dist && npm install`
|
||||||
|
|
||||||
|
### Test Failures
|
||||||
|
|
||||||
|
If tests fail:
|
||||||
|
|
||||||
|
- Run tests with verbose output: `npm test -- --reporter=verbose`
|
||||||
|
- Check specific test file: `npm test src/bitip-client.test.ts`
|
||||||
|
- Ensure mock data matches API responses
|
||||||
|
|
||||||
|
### Missing Dependencies
|
||||||
|
|
||||||
|
If dependencies are missing:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Clean install
|
||||||
|
rm -rf node_modules package-lock.json
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
### Before Every Release
|
||||||
|
|
||||||
|
1. ✅ **Update CHANGELOG.md** with all changes
|
||||||
|
2. ✅ **Run all tests** to ensure nothing is broken
|
||||||
|
3. ✅ **Update README.md** if API changed
|
||||||
|
4. ✅ **Review breaking changes** carefully
|
||||||
|
5. ✅ **Create git tag** for the release
|
||||||
|
6. ✅ **Test package locally** before publishing
|
||||||
|
|
||||||
|
### Test Package Locally
|
||||||
|
|
||||||
|
Before publishing, test the package in a separate project:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# In a test project
|
||||||
|
npm install d:/Git/Home/Bitip/src/clients/node
|
||||||
|
|
||||||
|
# Or link it
|
||||||
|
cd d:/Git/Home/Bitip/src/clients/node
|
||||||
|
npm link
|
||||||
|
|
||||||
|
cd /path/to/test/project
|
||||||
|
npm link @flare/bitip-client
|
||||||
|
```
|
||||||
|
|
||||||
|
### Version Checklist
|
||||||
|
|
||||||
|
- [ ] Version number updated in `package.json`
|
||||||
|
- [ ] CHANGELOG.md updated with changes
|
||||||
|
- [ ] All tests passing (`npm test`)
|
||||||
|
- [ ] Type checking passes (`npm run typecheck`)
|
||||||
|
- [ ] Package builds successfully (`npm run build`)
|
||||||
|
- [ ] README.md updated (if needed)
|
||||||
|
- [ ] Git changes committed
|
||||||
|
- [ ] Git tag created
|
||||||
|
- [ ] Package published to registry
|
||||||
|
- [ ] Changes pushed to Git repository
|
||||||
|
|
||||||
|
## Registry Configuration
|
||||||
|
|
||||||
|
### @flare Scope Configuration
|
||||||
|
|
||||||
|
The @flare scope is configured in `.npmrc`:
|
||||||
|
|
||||||
|
```
|
||||||
|
//lab.code-rove.com/:_authToken=${OWN_NPM_TOKEN}
|
||||||
|
@flare:registry=https://lab.code-rove.com/public-node-registry
|
||||||
|
```
|
||||||
|
|
||||||
|
This ensures all @flare packages use the lab registry.
|
||||||
|
|
||||||
|
### Multiple Registries
|
||||||
|
|
||||||
|
For other scopes or unscoped packages:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Default registry (npmjs)
|
||||||
|
npm config set registry https://registry.npmjs.org
|
||||||
|
|
||||||
|
# Different scope
|
||||||
|
npm config set @other-scope:registry https://other-registry.com
|
||||||
|
```
|
||||||
|
|
||||||
|
## Automated Release (Future Enhancement)
|
||||||
|
|
||||||
|
Consider setting up automated releases using GitHub Actions or similar CI/CD:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# .github/workflows/publish.yml
|
||||||
|
name: Publish Package
|
||||||
|
|
||||||
|
on:
|
||||||
|
push:
|
||||||
|
tags:
|
||||||
|
- 'v*'
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
publish:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
steps:
|
||||||
|
- uses: actions/checkout@v4
|
||||||
|
- uses: actions/setup-node@v4
|
||||||
|
with:
|
||||||
|
node-version: '18'
|
||||||
|
registry-url: 'https://lab.code-rove.com/public-node-registry'
|
||||||
|
- run: npm install
|
||||||
|
- run: npm run typecheck
|
||||||
|
- run: npm test
|
||||||
|
- run: npm run build
|
||||||
|
- run: npm publish
|
||||||
|
env:
|
||||||
|
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
| Command | Description |
|
||||||
|
| -------------------------- | ----------------------------- |
|
||||||
|
| `npm install` | Install dependencies |
|
||||||
|
| `npm run typecheck` | Check TypeScript types |
|
||||||
|
| `npm test` | Run tests |
|
||||||
|
| `npm run build` | Build package |
|
||||||
|
| `npm run publish:registry` | Publish to lab registry |
|
||||||
|
| `npm run publish:local` | Publish to local Verdaccio |
|
||||||
|
| `npm version patch` | Bump patch version |
|
||||||
|
| `npm version minor` | Bump minor version |
|
||||||
|
| `npm version major` | Bump major version |
|
||||||
|
| `git tag -a v1.0.0 -m "Release"` | Create git tag |
|
||||||
|
| `git push --tags` | Push tags to remote |
|
||||||
|
|
||||||
|
## Support
|
||||||
|
|
||||||
|
For questions or issues:
|
||||||
|
|
||||||
|
- **Repository**: https://lab.code-rove.com/gitea/tudor.stanciu/bitip
|
||||||
|
- **Bitip Service**: https://lab.code-rove.com/bitip/
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Copyright © 2025 Tudor Stanciu**
|
||||||
28
src/clients/node/eslint.config.mjs
Normal file
28
src/clients/node/eslint.config.mjs
Normal file
@ -0,0 +1,28 @@
|
|||||||
|
import tseslint from '@typescript-eslint/eslint-plugin';
|
||||||
|
import tsparser from '@typescript-eslint/parser';
|
||||||
|
|
||||||
|
export default [
|
||||||
|
{
|
||||||
|
files: ['src/**/*.ts'],
|
||||||
|
languageOptions: {
|
||||||
|
parser: tsparser,
|
||||||
|
parserOptions: {
|
||||||
|
project: './tsconfig.json',
|
||||||
|
ecmaVersion: 2020,
|
||||||
|
sourceType: 'module',
|
||||||
|
},
|
||||||
|
},
|
||||||
|
plugins: {
|
||||||
|
'@typescript-eslint': tseslint,
|
||||||
|
},
|
||||||
|
rules: {
|
||||||
|
'@typescript-eslint/no-explicit-any': 'warn',
|
||||||
|
'@typescript-eslint/explicit-function-return-type': 'off',
|
||||||
|
'@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
|
||||||
|
'@typescript-eslint/no-non-null-assertion': 'warn',
|
||||||
|
},
|
||||||
|
},
|
||||||
|
{
|
||||||
|
ignores: ['dist', 'node_modules', 'coverage', '*.config.ts', '*.config.mjs'],
|
||||||
|
},
|
||||||
|
];
|
||||||
91
src/clients/node/package.json
Normal file
91
src/clients/node/package.json
Normal file
@ -0,0 +1,91 @@
|
|||||||
|
{
|
||||||
|
"name": "@flare/bitip-client",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"description": "A TypeScript/Node.js client library for integrating with the Bitip GeoIP Service. Provides IP geolocation lookup, health checks, and version information retrieval.",
|
||||||
|
"author": {
|
||||||
|
"name": "Tudor Stanciu",
|
||||||
|
"email": "tudor.stanciu94@gmail.com",
|
||||||
|
"url": "https://lab.code-rove.com/tsp"
|
||||||
|
},
|
||||||
|
"license": "SEE LICENSE IN LICENSE",
|
||||||
|
"repository": {
|
||||||
|
"type": "git",
|
||||||
|
"url": "https://lab.code-rove.com/gitea/tudor.stanciu/bitip"
|
||||||
|
},
|
||||||
|
"keywords": [
|
||||||
|
"bitip",
|
||||||
|
"geoip",
|
||||||
|
"geolocation",
|
||||||
|
"ip-lookup",
|
||||||
|
"ip-geolocation",
|
||||||
|
"asn",
|
||||||
|
"maxmind",
|
||||||
|
"typescript",
|
||||||
|
"node"
|
||||||
|
],
|
||||||
|
"main": "./dist/index.js",
|
||||||
|
"module": "./dist/index.mjs",
|
||||||
|
"types": "./dist/index.d.ts",
|
||||||
|
"exports": {
|
||||||
|
".": {
|
||||||
|
"types": "./dist/index.d.ts",
|
||||||
|
"import": "./dist/index.mjs",
|
||||||
|
"require": "./dist/index.js"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"files": [
|
||||||
|
"dist",
|
||||||
|
"LICENSE",
|
||||||
|
"README.md",
|
||||||
|
"CHANGELOG.md"
|
||||||
|
],
|
||||||
|
"scripts": {
|
||||||
|
"build": "tsup",
|
||||||
|
"dev": "tsup --watch",
|
||||||
|
"test": "vitest run",
|
||||||
|
"test:watch": "vitest",
|
||||||
|
"test:ui": "vitest --ui",
|
||||||
|
"test:coverage": "vitest --coverage",
|
||||||
|
"typecheck": "tsc --noEmit",
|
||||||
|
"lint": "eslint src --ext .ts",
|
||||||
|
"lint:fix": "eslint src --ext .ts --fix",
|
||||||
|
"format": "prettier --write \"src/**/*.ts\"",
|
||||||
|
"format:check": "prettier --check \"src/**/*.ts\"",
|
||||||
|
"prepublishOnly": "npm run typecheck && npm test && npm run build",
|
||||||
|
"publish:registry": "npm publish",
|
||||||
|
"release:patch": "npm version patch --no-git-tag-version && npm run publish:registry",
|
||||||
|
"release:minor": "npm version minor --no-git-tag-version && npm run publish:registry",
|
||||||
|
"release:major": "npm version major --no-git-tag-version && npm run publish:registry"
|
||||||
|
},
|
||||||
|
"dependencies": {
|
||||||
|
"axios": "^1.12.2"
|
||||||
|
},
|
||||||
|
"devDependencies": {
|
||||||
|
"@types/node": "^24.7.2",
|
||||||
|
"@typescript-eslint/eslint-plugin": "^8.46.0",
|
||||||
|
"@typescript-eslint/parser": "^8.46.0",
|
||||||
|
"@vitest/coverage-v8": "^3.2.4",
|
||||||
|
"@vitest/ui": "^3.2.4",
|
||||||
|
"axios-mock-adapter": "^2.1.0",
|
||||||
|
"eslint": "^9.17.0",
|
||||||
|
"prettier": "^3.4.2",
|
||||||
|
"tsup": "^8.3.5",
|
||||||
|
"typescript": "^5.7.2",
|
||||||
|
"vitest": "^3.2.4"
|
||||||
|
},
|
||||||
|
"engines": {
|
||||||
|
"node": ">=18.0.0"
|
||||||
|
},
|
||||||
|
"publishConfig": {
|
||||||
|
"access": "public",
|
||||||
|
"registry": "https://lab.code-rove.com/public-node-registry"
|
||||||
|
},
|
||||||
|
"prettier": {
|
||||||
|
"semi": true,
|
||||||
|
"trailingComma": "es5",
|
||||||
|
"singleQuote": true,
|
||||||
|
"printWidth": 100,
|
||||||
|
"tabWidth": 2,
|
||||||
|
"arrowParens": "avoid"
|
||||||
|
}
|
||||||
|
}
|
||||||
345
src/clients/node/src/bitip-client.test.ts
Normal file
345
src/clients/node/src/bitip-client.test.ts
Normal file
@ -0,0 +1,345 @@
|
|||||||
|
// Copyright (c) 2025 Tudor Stanciu
|
||||||
|
|
||||||
|
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
|
||||||
|
import MockAdapter from 'axios-mock-adapter';
|
||||||
|
import axios from 'axios';
|
||||||
|
import { BitipClient } from './bitip-client';
|
||||||
|
import type {
|
||||||
|
HealthInfo,
|
||||||
|
VersionInfo,
|
||||||
|
IpLocation,
|
||||||
|
DetailedIpLocation,
|
||||||
|
BatchIpLookupResponse,
|
||||||
|
} from './types';
|
||||||
|
|
||||||
|
describe('BitipClient', () => {
|
||||||
|
let mock: MockAdapter;
|
||||||
|
const baseUrl = 'https://test-bitip.example.com';
|
||||||
|
const apiKey = 'test-api-key-12345';
|
||||||
|
|
||||||
|
beforeEach(() => {
|
||||||
|
mock = new MockAdapter(axios);
|
||||||
|
});
|
||||||
|
|
||||||
|
afterEach(() => {
|
||||||
|
mock.reset();
|
||||||
|
mock.restore();
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('constructor', () => {
|
||||||
|
it('should create client with valid options', () => {
|
||||||
|
const client = new BitipClient({ baseUrl, apiKey });
|
||||||
|
expect(client).toBeInstanceOf(BitipClient);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should throw error when options are null', () => {
|
||||||
|
expect(() => new BitipClient(null as any)).toThrow('Options cannot be null');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should throw error when baseUrl is missing', () => {
|
||||||
|
expect(() => new BitipClient({ baseUrl: '', apiKey: 'test' })).toThrow(
|
||||||
|
'Base URL is required'
|
||||||
|
);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should throw error when apiKey is missing', () => {
|
||||||
|
expect(() => new BitipClient({ baseUrl: 'http://test.com', apiKey: '' })).toThrow(
|
||||||
|
'API key is required'
|
||||||
|
);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('getHealth', () => {
|
||||||
|
it('should return health information', async () => {
|
||||||
|
const healthData: HealthInfo = {
|
||||||
|
status: 'healthy',
|
||||||
|
service: 'Bitip GeoIP Service',
|
||||||
|
timestamp: '2025-10-10T12:00:00Z',
|
||||||
|
};
|
||||||
|
|
||||||
|
mock.onGet(`${baseUrl}/api/health`).reply(200, healthData);
|
||||||
|
|
||||||
|
const client = new BitipClient({ baseUrl, apiKey });
|
||||||
|
const result = await client.getHealth();
|
||||||
|
|
||||||
|
expect(result).toEqual(healthData);
|
||||||
|
expect(result.status).toBe('healthy');
|
||||||
|
expect(result.service).toBe('Bitip GeoIP Service');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should handle error response', async () => {
|
||||||
|
mock.onGet(`${baseUrl}/api/health`).reply(500, { error: 'Internal Server Error' });
|
||||||
|
|
||||||
|
const client = new BitipClient({ baseUrl, apiKey });
|
||||||
|
await expect(client.getHealth()).rejects.toThrow();
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('getVersion', () => {
|
||||||
|
it('should return version information', async () => {
|
||||||
|
const versionData: VersionInfo = {
|
||||||
|
version: '1.0.0',
|
||||||
|
commitHash: 'abc123',
|
||||||
|
buildDate: '2025-10-10T12:00:00Z',
|
||||||
|
service: 'Bitip GeoIP Service',
|
||||||
|
};
|
||||||
|
|
||||||
|
mock.onGet(`${baseUrl}/api/version`).reply(200, versionData);
|
||||||
|
|
||||||
|
const client = new BitipClient({ baseUrl, apiKey });
|
||||||
|
const result = await client.getVersion();
|
||||||
|
|
||||||
|
expect(result).toEqual(versionData);
|
||||||
|
expect(result.version).toBe('1.0.0');
|
||||||
|
expect(result.commitHash).toBe('abc123');
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('getIpLocation', () => {
|
||||||
|
it('should return location for valid IPv4', async () => {
|
||||||
|
const locationData: IpLocation = {
|
||||||
|
ip: '8.8.8.8',
|
||||||
|
country: 'United States',
|
||||||
|
country_code: 'US',
|
||||||
|
is_in_european_union: false,
|
||||||
|
region: 'California',
|
||||||
|
region_code: 'CA',
|
||||||
|
city: 'Mountain View',
|
||||||
|
latitude: 37.4056,
|
||||||
|
longitude: -122.0775,
|
||||||
|
timezone: 'America/Los_Angeles',
|
||||||
|
postal_code: '94043',
|
||||||
|
continent_code: 'NA',
|
||||||
|
continent_name: 'North America',
|
||||||
|
organization: 'Google LLC',
|
||||||
|
asn: null,
|
||||||
|
};
|
||||||
|
|
||||||
|
mock
|
||||||
|
.onGet(`${baseUrl}/api/lookup`, { params: { ip: '8.8.8.8' } })
|
||||||
|
.reply(200, locationData);
|
||||||
|
|
||||||
|
const client = new BitipClient({ baseUrl, apiKey });
|
||||||
|
const result = await client.getIpLocation('8.8.8.8');
|
||||||
|
|
||||||
|
expect(result).toEqual(locationData);
|
||||||
|
expect(result.ip).toBe('8.8.8.8');
|
||||||
|
expect(result.country).toBe('United States');
|
||||||
|
expect(result.city).toBe('Mountain View');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should return location for valid IPv6', async () => {
|
||||||
|
const locationData: IpLocation = {
|
||||||
|
ip: '2001:4860:4860::8888',
|
||||||
|
country: 'United States',
|
||||||
|
country_code: 'US',
|
||||||
|
is_in_european_union: false,
|
||||||
|
region: 'California',
|
||||||
|
region_code: null,
|
||||||
|
city: 'Mountain View',
|
||||||
|
latitude: 37.4056,
|
||||||
|
longitude: -122.0775,
|
||||||
|
timezone: 'America/Los_Angeles',
|
||||||
|
postal_code: null,
|
||||||
|
continent_code: null,
|
||||||
|
continent_name: null,
|
||||||
|
organization: null,
|
||||||
|
asn: null,
|
||||||
|
};
|
||||||
|
|
||||||
|
mock
|
||||||
|
.onGet(`${baseUrl}/api/lookup`, { params: { ip: '2001:4860:4860::8888' } })
|
||||||
|
.reply(200, locationData);
|
||||||
|
|
||||||
|
const client = new BitipClient({ baseUrl, apiKey });
|
||||||
|
const result = await client.getIpLocation('2001:4860:4860::8888');
|
||||||
|
|
||||||
|
expect(result.ip).toBe('2001:4860:4860::8888');
|
||||||
|
expect(result.country).toBe('United States');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should throw error for invalid IP', async () => {
|
||||||
|
const client = new BitipClient({ baseUrl, apiKey });
|
||||||
|
await expect(client.getIpLocation('invalid-ip')).rejects.toThrow(
|
||||||
|
'The provided IP address is not valid.'
|
||||||
|
);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should throw error for empty IP', async () => {
|
||||||
|
const client = new BitipClient({ baseUrl, apiKey });
|
||||||
|
await expect(client.getIpLocation('')).rejects.toThrow(
|
||||||
|
'Value cannot be null or whitespace.'
|
||||||
|
);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should handle 404 not found', async () => {
|
||||||
|
mock
|
||||||
|
.onGet(`${baseUrl}/api/lookup`, { params: { ip: '1.2.3.4' } })
|
||||||
|
.reply(404, {
|
||||||
|
error: 'Not Found',
|
||||||
|
message: 'IP address not found in database',
|
||||||
|
});
|
||||||
|
|
||||||
|
const client = new BitipClient({ baseUrl, apiKey });
|
||||||
|
await expect(client.getIpLocation('1.2.3.4')).rejects.toThrow();
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('getDetailedIpLocation', () => {
|
||||||
|
it('should return detailed location information', async () => {
|
||||||
|
const detailedData: DetailedIpLocation = {
|
||||||
|
ip: '8.8.8.8',
|
||||||
|
location: {
|
||||||
|
country: {
|
||||||
|
iso_code: 'US',
|
||||||
|
names: { en: 'United States' },
|
||||||
|
is_in_european_union: false,
|
||||||
|
},
|
||||||
|
city: {
|
||||||
|
names: { en: 'Mountain View' },
|
||||||
|
},
|
||||||
|
location: {
|
||||||
|
latitude: 37.4056,
|
||||||
|
longitude: -122.0775,
|
||||||
|
time_zone: 'America/Los_Angeles',
|
||||||
|
},
|
||||||
|
},
|
||||||
|
asn: {
|
||||||
|
autonomousSystemNumber: 15169,
|
||||||
|
autonomousSystemOrganization: 'Google LLC',
|
||||||
|
ipAddress: '8.8.8.8',
|
||||||
|
network: '8.8.8.0/24',
|
||||||
|
},
|
||||||
|
};
|
||||||
|
|
||||||
|
mock
|
||||||
|
.onGet(`${baseUrl}/api/lookup/detailed`, { params: { ip: '8.8.8.8' } })
|
||||||
|
.reply(200, detailedData);
|
||||||
|
|
||||||
|
const client = new BitipClient({ baseUrl, apiKey });
|
||||||
|
const result = await client.getDetailedIpLocation('8.8.8.8');
|
||||||
|
|
||||||
|
expect(result.ip).toBe('8.8.8.8');
|
||||||
|
expect(result.location.country?.iso_code).toBe('US');
|
||||||
|
expect(result.asn.autonomousSystemNumber).toBe(15169);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should throw error for invalid IP', async () => {
|
||||||
|
const client = new BitipClient({ baseUrl, apiKey });
|
||||||
|
await expect(client.getDetailedIpLocation('invalid-ip')).rejects.toThrow(
|
||||||
|
'The provided IP address is not valid.'
|
||||||
|
);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('getBatchIpLocation', () => {
|
||||||
|
it('should return batch results for valid IPs', async () => {
|
||||||
|
const batchData: BatchIpLookupResponse = {
|
||||||
|
succeeded: [
|
||||||
|
{
|
||||||
|
ip: '8.8.8.8',
|
||||||
|
country: 'United States',
|
||||||
|
country_code: 'US',
|
||||||
|
is_in_european_union: false,
|
||||||
|
region: 'California',
|
||||||
|
region_code: 'CA',
|
||||||
|
city: 'Mountain View',
|
||||||
|
latitude: 37.4056,
|
||||||
|
longitude: -122.0775,
|
||||||
|
timezone: 'America/Los_Angeles',
|
||||||
|
postal_code: null,
|
||||||
|
continent_code: null,
|
||||||
|
continent_name: null,
|
||||||
|
organization: null,
|
||||||
|
asn: null,
|
||||||
|
},
|
||||||
|
{
|
||||||
|
ip: '1.1.1.1',
|
||||||
|
country: 'Australia',
|
||||||
|
country_code: 'AU',
|
||||||
|
is_in_european_union: false,
|
||||||
|
region: 'Queensland',
|
||||||
|
region_code: null,
|
||||||
|
city: 'Brisbane',
|
||||||
|
latitude: -27.4679,
|
||||||
|
longitude: 153.0281,
|
||||||
|
timezone: 'Australia/Brisbane',
|
||||||
|
postal_code: null,
|
||||||
|
continent_code: null,
|
||||||
|
continent_name: null,
|
||||||
|
organization: null,
|
||||||
|
asn: null,
|
||||||
|
},
|
||||||
|
],
|
||||||
|
failed: [],
|
||||||
|
};
|
||||||
|
|
||||||
|
mock.onPost(`${baseUrl}/api/lookup/batch`).reply(200, batchData);
|
||||||
|
|
||||||
|
const client = new BitipClient({ baseUrl, apiKey });
|
||||||
|
const result = await client.getBatchIpLocation(['8.8.8.8', '1.1.1.1']);
|
||||||
|
|
||||||
|
expect(result.succeeded).toHaveLength(2);
|
||||||
|
expect(result.failed).toHaveLength(0);
|
||||||
|
expect(result.succeeded[0]?.ip).toBe('8.8.8.8');
|
||||||
|
expect(result.succeeded[1]?.ip).toBe('1.1.1.1');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should handle mix of valid and invalid IPs', async () => {
|
||||||
|
const batchData: BatchIpLookupResponse = {
|
||||||
|
succeeded: [
|
||||||
|
{
|
||||||
|
ip: '8.8.8.8',
|
||||||
|
country: 'United States',
|
||||||
|
country_code: 'US',
|
||||||
|
is_in_european_union: false,
|
||||||
|
region: 'California',
|
||||||
|
region_code: null,
|
||||||
|
city: 'Mountain View',
|
||||||
|
latitude: null,
|
||||||
|
longitude: null,
|
||||||
|
timezone: null,
|
||||||
|
postal_code: null,
|
||||||
|
continent_code: null,
|
||||||
|
continent_name: null,
|
||||||
|
organization: null,
|
||||||
|
asn: null,
|
||||||
|
},
|
||||||
|
],
|
||||||
|
failed: [],
|
||||||
|
};
|
||||||
|
|
||||||
|
mock.onPost(`${baseUrl}/api/lookup/batch`).reply(200, batchData);
|
||||||
|
|
||||||
|
const client = new BitipClient({ baseUrl, apiKey });
|
||||||
|
const result = await client.getBatchIpLocation(['8.8.8.8', 'invalid-ip']);
|
||||||
|
|
||||||
|
expect(result.succeeded).toHaveLength(1);
|
||||||
|
expect(result.failed).toHaveLength(1);
|
||||||
|
expect(result.failed[0]?.ip).toBe('invalid-ip');
|
||||||
|
expect(result.failed[0]?.error).toBe('Invalid IP address format');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should return only errors when all IPs are invalid', async () => {
|
||||||
|
const client = new BitipClient({ baseUrl, apiKey });
|
||||||
|
const result = await client.getBatchIpLocation(['invalid-ip', 'not-an-ip']);
|
||||||
|
|
||||||
|
expect(result.succeeded).toHaveLength(0);
|
||||||
|
expect(result.failed).toHaveLength(2);
|
||||||
|
expect(result.failed[0]?.error).toBe('Invalid IP address format');
|
||||||
|
expect(result.failed[1]?.error).toBe('Invalid IP address format');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should throw error when IP list is null', async () => {
|
||||||
|
const client = new BitipClient({ baseUrl, apiKey });
|
||||||
|
await expect(client.getBatchIpLocation(null as any)).rejects.toThrow(
|
||||||
|
'IP list cannot be null'
|
||||||
|
);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('should throw error when IP list is empty', async () => {
|
||||||
|
const client = new BitipClient({ baseUrl, apiKey });
|
||||||
|
await expect(client.getBatchIpLocation([])).rejects.toThrow('IP list cannot be empty');
|
||||||
|
});
|
||||||
|
});
|
||||||
|
});
|
||||||
212
src/clients/node/src/bitip-client.ts
Normal file
212
src/clients/node/src/bitip-client.ts
Normal file
@ -0,0 +1,212 @@
|
|||||||
|
// Copyright (c) 2025 Tudor Stanciu
|
||||||
|
|
||||||
|
import axios, { AxiosInstance, AxiosError } from 'axios';
|
||||||
|
import {
|
||||||
|
BitipClientOptions,
|
||||||
|
HealthInfo,
|
||||||
|
VersionInfo,
|
||||||
|
IpLocation,
|
||||||
|
DetailedIpLocation,
|
||||||
|
BatchIpLookupRequest,
|
||||||
|
BatchIpLookupResponse,
|
||||||
|
BatchIpLookupError,
|
||||||
|
IBitipClient,
|
||||||
|
} from './types';
|
||||||
|
import { IpValidator } from './utils/ip-validator';
|
||||||
|
import { UrlNormalizer } from './utils/url-normalizer';
|
||||||
|
import { ApiKeys, ApiRoutes, Defaults } from './constants';
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Bitip API client implementation
|
||||||
|
*/
|
||||||
|
export class BitipClient implements IBitipClient {
|
||||||
|
private readonly httpClient: AxiosInstance;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Creates a new instance of BitipClient
|
||||||
|
* @param options - Configuration options for the client
|
||||||
|
*/
|
||||||
|
constructor(options: BitipClientOptions) {
|
||||||
|
if (!options) {
|
||||||
|
throw new Error('Options cannot be null');
|
||||||
|
}
|
||||||
|
|
||||||
|
if (!options.baseUrl) {
|
||||||
|
throw new Error('Base URL is required');
|
||||||
|
}
|
||||||
|
|
||||||
|
if (!options.apiKey) {
|
||||||
|
throw new Error('API key is required');
|
||||||
|
}
|
||||||
|
|
||||||
|
const baseURL = UrlNormalizer.ensureTrailingSlash(options.baseUrl, '/api');
|
||||||
|
const timeout = options.timeout ?? Defaults.Timeout;
|
||||||
|
|
||||||
|
this.httpClient = axios.create({
|
||||||
|
baseURL,
|
||||||
|
timeout,
|
||||||
|
headers: {
|
||||||
|
'Content-Type': 'application/json',
|
||||||
|
Accept: 'application/json',
|
||||||
|
[ApiKeys.HttpHeader]: options.apiKey,
|
||||||
|
},
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Get health status of the Bitip API
|
||||||
|
* @param signal - Optional AbortSignal for request cancellation
|
||||||
|
* @returns Health information
|
||||||
|
*/
|
||||||
|
async getHealth(signal?: AbortSignal): Promise<HealthInfo> {
|
||||||
|
try {
|
||||||
|
const response = await this.httpClient.get<HealthInfo>(ApiRoutes.Health, { signal });
|
||||||
|
return response.data;
|
||||||
|
} catch (error) {
|
||||||
|
throw this.handleError(error);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Get version information of the Bitip API
|
||||||
|
* @param signal - Optional AbortSignal for request cancellation
|
||||||
|
* @returns Version information
|
||||||
|
*/
|
||||||
|
async getVersion(signal?: AbortSignal): Promise<VersionInfo> {
|
||||||
|
try {
|
||||||
|
const response = await this.httpClient.get<VersionInfo>(ApiRoutes.Version, { signal });
|
||||||
|
return response.data;
|
||||||
|
} catch (error) {
|
||||||
|
throw this.handleError(error);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Get simple geolocation information for an IP address
|
||||||
|
* @param ip - IPv4 or IPv6 address to lookup
|
||||||
|
* @param signal - Optional AbortSignal for request cancellation
|
||||||
|
* @returns IP location information
|
||||||
|
* @throws {Error} If IP format is invalid
|
||||||
|
*/
|
||||||
|
async getIpLocation(ip: string, signal?: AbortSignal): Promise<IpLocation> {
|
||||||
|
IpValidator.validate(ip);
|
||||||
|
|
||||||
|
try {
|
||||||
|
const response = await this.httpClient.get<IpLocation>(ApiRoutes.Lookup, {
|
||||||
|
params: { ip },
|
||||||
|
signal,
|
||||||
|
});
|
||||||
|
return response.data;
|
||||||
|
} catch (error) {
|
||||||
|
throw this.handleError(error);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Get detailed geolocation information with ASN data for an IP address
|
||||||
|
* @param ip - IPv4 or IPv6 address to lookup
|
||||||
|
* @param signal - Optional AbortSignal for request cancellation
|
||||||
|
* @returns Detailed IP location information with ASN data
|
||||||
|
* @throws {Error} If IP format is invalid
|
||||||
|
*/
|
||||||
|
async getDetailedIpLocation(ip: string, signal?: AbortSignal): Promise<DetailedIpLocation> {
|
||||||
|
IpValidator.validate(ip);
|
||||||
|
|
||||||
|
try {
|
||||||
|
const response = await this.httpClient.get<DetailedIpLocation>(ApiRoutes.DetailedLookup, {
|
||||||
|
params: { ip },
|
||||||
|
signal,
|
||||||
|
});
|
||||||
|
return response.data;
|
||||||
|
} catch (error) {
|
||||||
|
throw this.handleError(error);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Get geolocation information for multiple IP addresses in a single request
|
||||||
|
* @param ips - Array of IPv4 or IPv6 addresses to lookup
|
||||||
|
* @param signal - Optional AbortSignal for request cancellation
|
||||||
|
* @returns Batch lookup response with succeeded and failed results
|
||||||
|
* @throws {Error} If IP list is empty or null
|
||||||
|
*/
|
||||||
|
async getBatchIpLocation(ips: string[], signal?: AbortSignal): Promise<BatchIpLookupResponse> {
|
||||||
|
if (!ips) {
|
||||||
|
throw new Error('IP list cannot be null');
|
||||||
|
}
|
||||||
|
|
||||||
|
if (ips.length === 0) {
|
||||||
|
throw new Error('IP list cannot be empty');
|
||||||
|
}
|
||||||
|
|
||||||
|
const validIps: string[] = [];
|
||||||
|
const clientErrors: BatchIpLookupError[] = [];
|
||||||
|
|
||||||
|
// Validate all IPs client-side
|
||||||
|
for (const ip of ips) {
|
||||||
|
if (IpValidator.isValid(ip)) {
|
||||||
|
validIps.push(ip);
|
||||||
|
} else {
|
||||||
|
clientErrors.push({
|
||||||
|
ip: ip ?? '',
|
||||||
|
error: 'Invalid IP address format',
|
||||||
|
});
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// If no valid IPs, return only client-side errors
|
||||||
|
if (validIps.length === 0) {
|
||||||
|
return {
|
||||||
|
succeeded: [],
|
||||||
|
failed: clientErrors,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
// Send valid IPs to API
|
||||||
|
try {
|
||||||
|
const request: BatchIpLookupRequest = { ips: validIps };
|
||||||
|
const response = await this.httpClient.post<BatchIpLookupResponse>(
|
||||||
|
ApiRoutes.BatchLookup,
|
||||||
|
request,
|
||||||
|
{ signal }
|
||||||
|
);
|
||||||
|
|
||||||
|
// Combine API results with client-side validation errors
|
||||||
|
return {
|
||||||
|
succeeded: response.data.succeeded,
|
||||||
|
failed: [...response.data.failed, ...clientErrors],
|
||||||
|
};
|
||||||
|
} catch (error) {
|
||||||
|
throw this.handleError(error);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Handles errors from axios requests
|
||||||
|
* @param error - Error from axios
|
||||||
|
* @returns Formatted error
|
||||||
|
*/
|
||||||
|
private handleError(error: unknown): Error {
|
||||||
|
if (axios.isAxiosError(error)) {
|
||||||
|
const axiosError = error as AxiosError;
|
||||||
|
|
||||||
|
if (axiosError.response) {
|
||||||
|
// Server responded with error status
|
||||||
|
const status = axiosError.response.status;
|
||||||
|
const data = axiosError.response.data as Error;
|
||||||
|
const message = data?.message || axiosError.message;
|
||||||
|
|
||||||
|
return new Error(`HTTP ${status}: ${message}`);
|
||||||
|
} else if (axiosError.request) {
|
||||||
|
// Request made but no response received
|
||||||
|
return new Error('No response received from server');
|
||||||
|
} else {
|
||||||
|
// Error setting up request
|
||||||
|
return new Error(axiosError.message);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Unknown error type
|
||||||
|
return error instanceof Error ? error : new Error('Unknown error occurred');
|
||||||
|
}
|
||||||
|
}
|
||||||
27
src/clients/node/src/constants.ts
Normal file
27
src/clients/node/src/constants.ts
Normal file
@ -0,0 +1,27 @@
|
|||||||
|
// Copyright (c) 2025 Tudor Stanciu
|
||||||
|
|
||||||
|
/**
|
||||||
|
* API key constants
|
||||||
|
*/
|
||||||
|
export const ApiKeys = {
|
||||||
|
HttpHeader: 'X-API-Key',
|
||||||
|
} as const;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* API route constants
|
||||||
|
*/
|
||||||
|
export const ApiRoutes = {
|
||||||
|
Health: 'health',
|
||||||
|
Version: 'version',
|
||||||
|
Lookup: 'lookup',
|
||||||
|
DetailedLookup: 'lookup/detailed',
|
||||||
|
BatchLookup: 'lookup/batch',
|
||||||
|
} as const;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Default values
|
||||||
|
*/
|
||||||
|
export const Defaults = {
|
||||||
|
Timeout: 30000, // 30 seconds
|
||||||
|
MissingValue: 'Unknown',
|
||||||
|
} as const;
|
||||||
43
src/clients/node/src/index.ts
Normal file
43
src/clients/node/src/index.ts
Normal file
@ -0,0 +1,43 @@
|
|||||||
|
// Copyright (c) 2025 Tudor Stanciu
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Bitip Client Library
|
||||||
|
*
|
||||||
|
* A TypeScript/Node.js client for the Bitip GeoIP Service.
|
||||||
|
* Provides IP geolocation lookup, health checks, and version information.
|
||||||
|
*
|
||||||
|
* @packageDocumentation
|
||||||
|
*/
|
||||||
|
|
||||||
|
// Main client
|
||||||
|
export { BitipClient } from './bitip-client';
|
||||||
|
|
||||||
|
// Types and interfaces
|
||||||
|
export type {
|
||||||
|
BitipClientOptions,
|
||||||
|
HealthInfo,
|
||||||
|
VersionInfo,
|
||||||
|
IpLocation,
|
||||||
|
DetailedIpLocation,
|
||||||
|
BatchIpLookupRequest,
|
||||||
|
BatchIpLookupResponse,
|
||||||
|
BatchIpLookupError,
|
||||||
|
ErrorResponse,
|
||||||
|
IBitipClient,
|
||||||
|
CountryInfo,
|
||||||
|
CityInfo,
|
||||||
|
Subdivision,
|
||||||
|
LocationInfo,
|
||||||
|
PostalInfo,
|
||||||
|
ContinentInfo,
|
||||||
|
TraitsInfo,
|
||||||
|
GeoIpLocation,
|
||||||
|
AsnInfo,
|
||||||
|
} from './types';
|
||||||
|
|
||||||
|
// Utilities
|
||||||
|
export { IpValidator } from './utils/ip-validator';
|
||||||
|
export { UrlNormalizer } from './utils/url-normalizer';
|
||||||
|
|
||||||
|
// Constants
|
||||||
|
export { ApiKeys, ApiRoutes, Defaults } from './constants';
|
||||||
222
src/clients/node/src/types.ts
Normal file
222
src/clients/node/src/types.ts
Normal file
@ -0,0 +1,222 @@
|
|||||||
|
// Copyright (c) 2025 Tudor Stanciu
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Configuration options for BitipClient
|
||||||
|
*/
|
||||||
|
export interface BitipClientOptions {
|
||||||
|
/**
|
||||||
|
* Base URL of the Bitip API instance (e.g., "https://bitip.example.com/api")
|
||||||
|
*/
|
||||||
|
baseUrl: string;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* API key for authentication
|
||||||
|
*/
|
||||||
|
apiKey: string;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Request timeout in milliseconds (default: 30000)
|
||||||
|
*/
|
||||||
|
timeout?: number;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Health information response
|
||||||
|
*/
|
||||||
|
export interface HealthInfo {
|
||||||
|
status: string;
|
||||||
|
service: string;
|
||||||
|
timestamp: string;
|
||||||
|
error?: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Version information response
|
||||||
|
*/
|
||||||
|
export interface VersionInfo {
|
||||||
|
version: string;
|
||||||
|
commitHash: string;
|
||||||
|
buildDate: string;
|
||||||
|
service?: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Simple IP location response
|
||||||
|
*/
|
||||||
|
export interface IpLocation {
|
||||||
|
ip: string;
|
||||||
|
country: string;
|
||||||
|
country_code: string;
|
||||||
|
is_in_european_union: boolean;
|
||||||
|
region: string;
|
||||||
|
region_code: string | null;
|
||||||
|
city: string;
|
||||||
|
latitude: number | null;
|
||||||
|
longitude: number | null;
|
||||||
|
timezone: string | null;
|
||||||
|
postal_code: string | null;
|
||||||
|
continent_code: string | null;
|
||||||
|
continent_name: string | null;
|
||||||
|
organization: string | null;
|
||||||
|
asn: number | null;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Country information in detailed response
|
||||||
|
*/
|
||||||
|
export interface CountryInfo {
|
||||||
|
iso_code?: string;
|
||||||
|
names?: Record<string, string>;
|
||||||
|
is_in_european_union?: boolean;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* City information in detailed response
|
||||||
|
*/
|
||||||
|
export interface CityInfo {
|
||||||
|
names?: Record<string, string>;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Subdivision (state/province) information
|
||||||
|
*/
|
||||||
|
export interface Subdivision {
|
||||||
|
iso_code?: string;
|
||||||
|
names?: Record<string, string>;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Location coordinates and timezone
|
||||||
|
*/
|
||||||
|
export interface LocationInfo {
|
||||||
|
latitude?: number;
|
||||||
|
longitude?: number;
|
||||||
|
time_zone?: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Postal code information
|
||||||
|
*/
|
||||||
|
export interface PostalInfo {
|
||||||
|
code?: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Continent information
|
||||||
|
*/
|
||||||
|
export interface ContinentInfo {
|
||||||
|
code?: string;
|
||||||
|
names?: Record<string, string>;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Traits information (proxy, satellite, etc.)
|
||||||
|
*/
|
||||||
|
export interface TraitsInfo {
|
||||||
|
is_anonymous_proxy?: boolean;
|
||||||
|
is_satellite_provider?: boolean;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Detailed GeoIP location data
|
||||||
|
*/
|
||||||
|
export interface GeoIpLocation {
|
||||||
|
country?: CountryInfo;
|
||||||
|
city?: CityInfo;
|
||||||
|
subdivisions?: Subdivision[];
|
||||||
|
location?: LocationInfo;
|
||||||
|
postal?: PostalInfo;
|
||||||
|
continent?: ContinentInfo;
|
||||||
|
registered_country?: CountryInfo;
|
||||||
|
traits?: TraitsInfo;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* ASN (Autonomous System Number) information
|
||||||
|
*/
|
||||||
|
export interface AsnInfo {
|
||||||
|
autonomousSystemNumber?: number;
|
||||||
|
autonomousSystemOrganization?: string;
|
||||||
|
ipAddress?: string;
|
||||||
|
network?: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Detailed IP location response with full GeoIP and ASN data
|
||||||
|
*/
|
||||||
|
export interface DetailedIpLocation {
|
||||||
|
ip: string;
|
||||||
|
location: GeoIpLocation;
|
||||||
|
asn: AsnInfo;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Batch lookup request body
|
||||||
|
*/
|
||||||
|
export interface BatchIpLookupRequest {
|
||||||
|
ips: string[];
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Batch lookup error entry
|
||||||
|
*/
|
||||||
|
export interface BatchIpLookupError {
|
||||||
|
ip: string;
|
||||||
|
error: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Batch lookup response
|
||||||
|
*/
|
||||||
|
export interface BatchIpLookupResponse {
|
||||||
|
succeeded: IpLocation[];
|
||||||
|
failed: BatchIpLookupError[];
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Error response from API
|
||||||
|
*/
|
||||||
|
export interface ErrorResponse {
|
||||||
|
error: string;
|
||||||
|
message: string;
|
||||||
|
ip?: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Bitip API client interface
|
||||||
|
*/
|
||||||
|
export interface IBitipClient {
|
||||||
|
/**
|
||||||
|
* Get health status of the Bitip API
|
||||||
|
*/
|
||||||
|
getHealth(signal?: AbortSignal): Promise<HealthInfo>;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Get version information of the Bitip API
|
||||||
|
*/
|
||||||
|
getVersion(signal?: AbortSignal): Promise<VersionInfo>;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Get simple geolocation information for an IP address
|
||||||
|
* @param ip - IPv4 or IPv6 address to lookup
|
||||||
|
* @param signal - Optional AbortSignal for request cancellation
|
||||||
|
* @throws {Error} If IP format is invalid
|
||||||
|
*/
|
||||||
|
getIpLocation(ip: string, signal?: AbortSignal): Promise<IpLocation>;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Get detailed geolocation information with ASN data for an IP address
|
||||||
|
* @param ip - IPv4 or IPv6 address to lookup
|
||||||
|
* @param signal - Optional AbortSignal for request cancellation
|
||||||
|
* @throws {Error} If IP format is invalid
|
||||||
|
*/
|
||||||
|
getDetailedIpLocation(ip: string, signal?: AbortSignal): Promise<DetailedIpLocation>;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Get geolocation information for multiple IP addresses in a single request
|
||||||
|
* @param ips - Array of IPv4 or IPv6 addresses to lookup
|
||||||
|
* @param signal - Optional AbortSignal for request cancellation
|
||||||
|
* @throws {Error} If IP list is empty or null
|
||||||
|
*/
|
||||||
|
getBatchIpLocation(ips: string[], signal?: AbortSignal): Promise<BatchIpLookupResponse>;
|
||||||
|
}
|
||||||
62
src/clients/node/src/utils/ip-validator.ts
Normal file
62
src/clients/node/src/utils/ip-validator.ts
Normal file
@ -0,0 +1,62 @@
|
|||||||
|
// Copyright (c) 2025 Tudor Stanciu
|
||||||
|
|
||||||
|
import { isIP } from 'node:net';
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Validates and checks IP addresses
|
||||||
|
*/
|
||||||
|
export class IpValidator {
|
||||||
|
/**
|
||||||
|
* Validates an IP address and throws an error if invalid
|
||||||
|
* @param ip - IP address to validate
|
||||||
|
* @throws {Error} If IP is null, empty, or invalid format
|
||||||
|
*/
|
||||||
|
static validate(ip: string): void {
|
||||||
|
if (!ip || ip.trim().length === 0) {
|
||||||
|
throw new Error('Value cannot be null or whitespace.');
|
||||||
|
}
|
||||||
|
|
||||||
|
if (!this.isValid(ip)) {
|
||||||
|
throw new Error('The provided IP address is not valid.');
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Checks if an IP address is valid (IPv4 or IPv6)
|
||||||
|
* @param ip - IP address to check
|
||||||
|
* @returns true if valid IPv4 or IPv6 address, false otherwise
|
||||||
|
*/
|
||||||
|
static isValid(ip: string): boolean {
|
||||||
|
if (!ip || ip.trim().length === 0) {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
|
return isIP(ip.trim()) !== 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Checks if an IP address is IPv4
|
||||||
|
* @param ip - IP address to check
|
||||||
|
* @returns true if valid IPv4 address, false otherwise
|
||||||
|
*/
|
||||||
|
static isIPv4(ip: string): boolean {
|
||||||
|
if (!ip || ip.trim().length === 0) {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
|
return isIP(ip.trim()) === 4;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Checks if an IP address is IPv6
|
||||||
|
* @param ip - IP address to check
|
||||||
|
* @returns true if valid IPv6 address, false otherwise
|
||||||
|
*/
|
||||||
|
static isIPv6(ip: string): boolean {
|
||||||
|
if (!ip || ip.trim().length === 0) {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
|
||||||
|
return isIP(ip.trim()) === 6;
|
||||||
|
}
|
||||||
|
}
|
||||||
51
src/clients/node/src/utils/url-normalizer.ts
Normal file
51
src/clients/node/src/utils/url-normalizer.ts
Normal file
@ -0,0 +1,51 @@
|
|||||||
|
// Copyright (c) 2025 Tudor Stanciu
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Normalizes URLs for API client usage
|
||||||
|
*/
|
||||||
|
export class UrlNormalizer {
|
||||||
|
/**
|
||||||
|
* Ensures a URL ends with a trailing slash and appends a suffix if provided
|
||||||
|
* @param baseUrl - Base URL to normalize
|
||||||
|
* @param suffix - Optional suffix to append (default: '/api')
|
||||||
|
* @returns Normalized URL with trailing slash
|
||||||
|
*/
|
||||||
|
static ensureTrailingSlash(baseUrl: string, suffix: string = '/api'): string {
|
||||||
|
if (!baseUrl) {
|
||||||
|
throw new Error('Base URL cannot be null or empty');
|
||||||
|
}
|
||||||
|
|
||||||
|
let normalized = baseUrl.trim();
|
||||||
|
|
||||||
|
// Remove trailing slash if present
|
||||||
|
if (normalized.endsWith('/')) {
|
||||||
|
normalized = normalized.slice(0, -1);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Add suffix if not already present
|
||||||
|
if (suffix && !normalized.endsWith(suffix)) {
|
||||||
|
// Remove leading slash from suffix if present
|
||||||
|
const cleanSuffix = suffix.startsWith('/') ? suffix : `/${suffix}`;
|
||||||
|
normalized += cleanSuffix;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Ensure trailing slash
|
||||||
|
if (!normalized.endsWith('/')) {
|
||||||
|
normalized += '/';
|
||||||
|
}
|
||||||
|
|
||||||
|
return normalized;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Combines base URL with path segments
|
||||||
|
* @param baseUrl - Base URL
|
||||||
|
* @param path - Path to append
|
||||||
|
* @returns Combined URL
|
||||||
|
*/
|
||||||
|
static combine(baseUrl: string, path: string): string {
|
||||||
|
const normalizedBase = baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
|
||||||
|
const normalizedPath = path.startsWith('/') ? path.slice(1) : path;
|
||||||
|
return normalizedBase + normalizedPath;
|
||||||
|
}
|
||||||
|
}
|
||||||
36
src/clients/node/tsconfig.json
Normal file
36
src/clients/node/tsconfig.json
Normal file
@ -0,0 +1,36 @@
|
|||||||
|
{
|
||||||
|
"compilerOptions": {
|
||||||
|
"target": "ES2020",
|
||||||
|
"module": "ESNext",
|
||||||
|
"lib": ["ES2020"],
|
||||||
|
"moduleResolution": "bundler",
|
||||||
|
"resolveJsonModule": true,
|
||||||
|
"allowJs": false,
|
||||||
|
"checkJs": false,
|
||||||
|
"outDir": "./dist",
|
||||||
|
"rootDir": "./src",
|
||||||
|
"declaration": true,
|
||||||
|
"declarationMap": true,
|
||||||
|
"sourceMap": true,
|
||||||
|
"removeComments": false,
|
||||||
|
"strict": true,
|
||||||
|
"noImplicitAny": true,
|
||||||
|
"strictNullChecks": true,
|
||||||
|
"strictFunctionTypes": true,
|
||||||
|
"strictBindCallApply": true,
|
||||||
|
"strictPropertyInitialization": true,
|
||||||
|
"noImplicitThis": true,
|
||||||
|
"alwaysStrict": true,
|
||||||
|
"noUnusedLocals": true,
|
||||||
|
"noUnusedParameters": true,
|
||||||
|
"noImplicitReturns": true,
|
||||||
|
"noFallthroughCasesInSwitch": true,
|
||||||
|
"noUncheckedIndexedAccess": true,
|
||||||
|
"esModuleInterop": true,
|
||||||
|
"allowSyntheticDefaultImports": true,
|
||||||
|
"forceConsistentCasingInFileNames": true,
|
||||||
|
"skipLibCheck": true
|
||||||
|
},
|
||||||
|
"include": ["src/**/*"],
|
||||||
|
"exclude": ["node_modules", "dist", "**/*.spec.ts", "**/*.test.ts"]
|
||||||
|
}
|
||||||
14
src/clients/node/tsup.config.ts
Normal file
14
src/clients/node/tsup.config.ts
Normal file
@ -0,0 +1,14 @@
|
|||||||
|
import { defineConfig } from 'tsup';
|
||||||
|
|
||||||
|
export default defineConfig({
|
||||||
|
entry: ['src/index.ts'],
|
||||||
|
format: ['cjs', 'esm'],
|
||||||
|
dts: true,
|
||||||
|
clean: true,
|
||||||
|
sourcemap: true,
|
||||||
|
splitting: false,
|
||||||
|
minify: false,
|
||||||
|
treeshake: true,
|
||||||
|
target: 'es2020',
|
||||||
|
outDir: 'dist',
|
||||||
|
});
|
||||||
20
src/clients/node/vitest.config.ts
Normal file
20
src/clients/node/vitest.config.ts
Normal file
@ -0,0 +1,20 @@
|
|||||||
|
import { defineConfig } from 'vitest/config';
|
||||||
|
|
||||||
|
export default defineConfig({
|
||||||
|
test: {
|
||||||
|
globals: true,
|
||||||
|
environment: 'node',
|
||||||
|
coverage: {
|
||||||
|
provider: 'v8',
|
||||||
|
reporter: ['text', 'json', 'html', 'lcov'],
|
||||||
|
exclude: [
|
||||||
|
'node_modules/',
|
||||||
|
'dist/',
|
||||||
|
'**/*.config.ts',
|
||||||
|
'**/*.config.js',
|
||||||
|
'**/types.ts',
|
||||||
|
'**/constants.ts',
|
||||||
|
],
|
||||||
|
},
|
||||||
|
},
|
||||||
|
});
|
||||||
Loading…
x
Reference in New Issue
Block a user