npm package: @geoipapi/sdk
Description: <div align="center">
Author: Speakeasy
Latest version: 0.0.1

<div align="center">

# 🌍 GeoIP API TypeScript SDK

**Developer-friendly & type-safe TypeScript SDK for enterprise IP geolocation**

[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://badge.fury.io/js/geoipapi.svg)](https://badge.fury.io/js/geoipapi)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)

[Features](#-features) • [Installation](#-installation) • [Quick Start](#-quick-start) • [API Reference](#-api-reference) • [Examples](#-examples)

</div>

---

## 📋 Table of Contents

- [🎯 Overview](#-overview)
- [✨ Features](#-features)
- [🚀 Installation](#-installation)
- [⚡ Quick Start](#-quick-start)
- [📖 API Reference](#-api-reference)
- [💡 Examples](#-examples)
- [🏗️ Project Structure](#️-project-structure)
- [⚙️ Configuration](#️-configuration)
- [🧪 Testing](#-testing)
- [🤝 Contributing](#-contributing)
- [📝 License](#-license)

## 🎯 Overview

The **GeoIP API TypeScript SDK** is a high-performance, enterprise-grade client library that provides real-time IP geolocation data for personalization, analytics, and security applications. Built with TypeScript-first design principles, it offers complete type safety and an intuitive developer experience.

### What makes this SDK special?

- **🔒 Type-Safe**: Full TypeScript support with comprehensive type definitions
- **⚡ High Performance**: Optimized for speed with minimal bundle size
- **🌐 Multiple Formats**: Support for JSON, JSONP, XML, and YAML responses
- **🔄 Auto-Retry**: Built-in retry logic with configurable backoff strategies
- **📦 Tree-Shakable**: Import only what you need for optimal bundle size
- **🎯 MCP Support**: Compatible with Model Context Protocol for AI applications

## ✨ Features

| Feature | Description |
|---------|-------------|
| **IP Detection** | Automatically detect visitor's IP address |
| **Geolocation Data** | Get detailed location information including country, city, timezone |
| **ISP Information** | Access ASN, network provider, and connection type data |
| **Currency & Language** | Retrieve local currency codes and language preferences |
| **Security Insights** | Identify proxy, VPN, and hosting provider connections |
| **Flexible Formats** | Support for JSON, XML, YAML, and JSONP responses |
| **Rate Limiting** | Built-in respect for API rate limits |
| **Error Handling** | Comprehensive error types with detailed information |

## 🚀 Installation

Choose your preferred package manager:

```bash
# NPM
npm install @geoipapi/sdk

# PNPM
pnpm add @geoipapi/sdk

# Bun
bun add @geoipapi/sdk

# Yarn
yarn add @geoipapi/sdk zod
```

> **Note**: Yarn requires manual installation of the `zod` peer dependency.

## ⚡ Quick Start

```typescript
import { GeoIp } from "geoipapi";

// Initialize the client
const geoIp = new GeoIp();

// Get your current IP address
async function getCurrentIP() {
  try {
    const ip = await geoIp.geoIPEndpoints.getIp();
    console.log("Your IP:", ip);
  } catch (error) {
    console.error("Failed to get IP:", error);
  }
}

// Get detailed geolocation data
async function getLocationData() {
  try {
    const result = await geoIp.geoIPEndpoints.getIpData();
    
    console.log("Location data:", result);
    /*
    Expected output:
    {"ip":"103.105.180.16","type":"IPv4","country":{"is_eu_member":false,"currency_code":"CNY","continent":"AS","name":"China","country_code":"CN","state":"Wuhan Shi","city":"Hankou (Wuchang Qu)","zip":null,"timezone":"Asia/Shanghai"},"location":{"latitude":30.552964677185926,"longitude":114.34486005697988},"asn":{"number":63539,"name":"Cloud Union (HuBei) Network Technology Co., Ltd","network":"103.105.180.0/22","type":"HOSTING"}}
    */
  } catch (error) {
    console.error("Failed to get location data:", error);
  }
}

// Run the examples
getCurrentIP();
getLocationData();
```

## 📖 API Reference

### Core Methods

#### `getIp()`
Get the current IP address of the requester.

```typescript
const ip: string = await geoIp.geoIPEndpoints.getIp();
```

#### `getIpData(request?)`
Get comprehensive geolocation data for your IP address.

```typescript
const data = await geoIp.geoIPEndpoints.getIpData();
```

### Response Schema

```typescript
interface GeoLocationResponse {
  ip: string;
  type: "IPv4" | "IPv6";
  country: {
    name: string;
    country_code: string;
    currency_code: string;
    is_eu_member: boolean;
    continent: string;
    state?: string;
    city?: string;
    zip?: string;
    timezone: string;
  };
  location: {
    latitude: number;
    longitude: number;
  };
  asn: {
    number: number;
    name: string;
    network: string;
    type: string;
  };
}
```

## 💡 Examples

### Basic Usage

```typescript
import { GeoIp } from "geoipapi";

const client = new GeoIp();

// Simple IP lookup
const userIP = await client.geoIPEndpoints.getIp();
const locationData = await client.geoIPEndpoints.getIpData();
```

### Error Handling

```typescript
import { GeoIp } from "geoipapi";
import * as errors from "geoipapi/models/errors";

const client = new GeoIp();

try {
  const result = await client.geoIPEndpoints.getIpData({ ip: "invalid-ip" });
} catch (error) {
  if (error instanceof errors.HTTPValidationError) {
    console.log("Validation error:", error.data$.detail);
  } else if (error instanceof errors.GeoIPError) {
    console.log("API error:", error.message, error.statusCode);
  } else {
    console.log("Unexpected error:", error);
  }
}
```

### Standalone Functions (Tree-Shaking Friendly)

```typescript
import { GeoIpCore } from "geoipapi/core.js";
import { geoIPEndpointsGetIP, geoIPEndpointsGetIPData } from "geoipapi/funcs";

const client = new GeoIpCore();

// Tree-shakable function calls
const ipResult = await geoIPEndpointsGetIP(client);
const dataResult = await geoIPEndpointsGetIPData(client, { ip: "1.1.1.1" });

if (ipResult.ok) {
  console.log("IP:", ipResult.value);
}

if (dataResult.ok) {
  console.log("Data:", dataResult.value);
}
```

### Custom HTTP Client

```typescript
import { GeoIp, HTTPClient } from "geoipapi";

const httpClient = new HTTPClient({
  fetcher: (request) => fetch(request)
});

// Add custom headers
httpClient.addHook("beforeRequest", (request) => {
  const nextRequest = new Request(request, {
    signal: request.signal || AbortSignal.timeout(10000)
  });
  nextRequest.headers.set("User-Agent", "MyApp/1.0");
  return nextRequest;
});

// Custom error logging
httpClient.addHook("requestError", (error, request) => {
  console.error(`Request failed: ${request.method} ${request.url}`, error);
});

const client = new GeoIp({ httpClient });
```

## 🏗️ Project Structure

```
geo-ip-typescript/
├── 📁 src/                    # Source code
│   ├── 📁 models/             # TypeScript type definitions
│   ├── 📁 lib/                # Core SDK functionality
│   └── 📁 funcs/              # Standalone functions
├── 📁 docs/                   # API documentation
│   └── 📁 sdks/               # SDK-specific docs
├── 📁 dist/                   # Compiled JavaScript
├── 📄 README.md               # This file
├── 📄 USAGE.md                # Usage examples
├── 📄 CONTRIBUTING.md         # Contribution guidelines
├── 📄 package.json            # Package configuration
└── 📄 tsconfig.json           # TypeScript configuration
```

## ⚙️ Configuration

### Environment Variables

```bash
# Enable debug logging
GEOIP_DEBUG=true

# Custom API endpoint (optional)
GEOIP_API_URL=https://api.geoipapi.com
```

### Client Configuration

```typescript
const client = new GeoIp({
  serverURL: "https://api.geoipapi.com",  // Custom API URL
  retryConfig: {                          // Retry configuration
    strategy: "backoff",
    backoff: {
      initialInterval: 1000,
      maxInterval: 30000,
      exponent: 1.5,
    },
  },
  debugLogger: console,                   // Debug logging
});
```

## 🧪 Testing

This SDK includes comprehensive test coverage. For supported JavaScript runtimes, please consult [RUNTIMES.md](RUNTIMES.md).

```bash
# Run tests
npm test

# Run with coverage
npm run test:coverage

# Run linting
npm run lint

# Type checking
npm run type-check
```

## 🤝 Contributing

We welcome contributions! However, please note that this repository contains generated code.

### How to Contribute

1. **Report Issues**: Open a GitHub issue with detailed information about bugs or feature requests
2. **Provide Feedback**: Share your experience and suggestions for improvements
3. **Documentation**: Help improve examples and documentation

### Issue Guidelines

When reporting issues, please include:
- Clear and descriptive title
- Steps to reproduce the issue
- Expected vs actual behavior
- Environment information (`npx envinfo`)
- Relevant logs or error messages

For more details, see [CONTRIBUTING.md](CONTRIBUTING.md).

## 📝 License

This project is licensed under the [MIT License](https://opensource.org/licenses/MIT).

---

<div align="center">

**Made with ❤️ for developers who need reliable IP geolocation data**

[⭐ Star this repo](https://github.com/geoipapi/geo-ip-typescript) • [📖 Read the docs](docs/) • [🐛 Report issues](https://github.com/geoipapi/geo-ip-typescript/issues)

</div>