ipdata.go

// Package ipdata is the official Go client for the ipdata.info IP geolocation,
// ASN, and threat-intelligence API. See https://ipdata.info.
package ipdata

import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"net/url"
	"strconv"
	"time"
)

const (
	// DefaultBaseURL is the free tier host (50 req/min, no key).
	DefaultBaseURL = "https://ipdata.info"
	// ProBaseURL is the paid host used automatically when an API key is set.
	ProBaseURL = "https://pro.ipdata.info"

	version   = "0.1.0"
	userAgent = "ipdata-go/" + version
)

// Client is an ipdata.info API client. The zero value is not usable; call New.
type Client struct {
	apiKey  string
	baseURL string
	http    *http.Client
}

// Option configures a Client.
type Option func(*Client)

// WithAPIKey sets the API key (sent as the X-Api-Key header) and, unless a base
// URL was set explicitly, switches the default host to the pro tier.
func WithAPIKey(key string) Option { return func(c *Client) { c.apiKey = key } }

// WithBaseURL overrides the API host (no trailing slash).
func WithBaseURL(u string) Option { return func(c *Client) { c.baseURL = u } }

// WithHTTPClient supplies a custom *http.Client (e.g. for a proxy or timeout).
func WithHTTPClient(h *http.Client) Option { return func(c *Client) { c.http = h } }

// New builds a Client. Without options it targets the free tier.
func New(opts ...Option) *Client {
	c := &Client{http: &http.Client{Timeout: 10 * time.Second}}
	for _, o := range opts {
		o(c)
	}
	if c.baseURL == "" {
		if c.apiKey != "" {
			c.baseURL = ProBaseURL
		} else {
			c.baseURL = DefaultBaseURL
		}
	}
	return c
}

// Lookup returns the full record for ip. Pass "" for the caller's own IP.
func (c *Client) Lookup(ctx context.Context, ip string) (*IPInfo, error) {
	var out IPInfo
	if err := c.get(ctx, "/json/"+url.PathEscape(ip), &out); err != nil {
		return nil, err
	}
	return &out, nil
}

// Geo returns the compact geo subset for ip.
func (c *Client) Geo(ctx context.Context, ip string) (*GeoInfo, error) {
	var out GeoInfo
	if err := c.get(ctx, "/api/v1/"+url.PathEscape(ip)+"/geo", &out); err != nil {
		return nil, err
	}
	return &out, nil
}

// ASN returns the compact ASN subset for ip.
func (c *Client) ASN(ctx context.Context, ip string) (*ASNBrief, error) {
	var out ASNBrief
	if err := c.get(ctx, "/api/v1/"+url.PathEscape(ip)+"/asn", &out); err != nil {
		return nil, err
	}
	return &out, nil
}

// Batch looks up many IPs at once. Requires an API key (paid tier).
func (c *Client) Batch(ctx context.Context, ips []string) ([]IPInfo, error) {
	body, err := json.Marshal(ips)
	if err != nil {
		return nil, err
	}
	var out []IPInfo
	if err := c.do(ctx, http.MethodPost, "/api/v1/batch", bytes.NewReader(body), &out); err != nil {
		return nil, err
	}
	return out, nil
}

// ASNDetail returns the detailed ASN record (prefixes, peering) as a raw map.
func (c *Client) ASNDetail(ctx context.Context, number int) (map[string]any, error) {
	var out map[string]any
	if err := c.get(ctx, "/api/v1/asn/"+strconv.Itoa(number), &out); err != nil {
		return nil, err
	}
	return out, nil
}

// ASNWhoisHistory returns the ASN whois history as a raw map.
func (c *Client) ASNWhoisHistory(ctx context.Context, number int) (map[string]any, error) {
	var out map[string]any
	if err := c.get(ctx, "/api/v1/asn/"+strconv.Itoa(number)+"/whois-history", &out); err != nil {
		return nil, err
	}
	return out, nil
}

// ASNChanges returns the ASN change feed as a raw value.
func (c *Client) ASNChanges(ctx context.Context) (any, error) {
	var out any
	if err := c.get(ctx, "/api/v1/asn-changes", &out); err != nil {
		return nil, err
	}
	return out, nil
}

// ThreatDomain looks up a domain in the threat-intel store.
func (c *Client) ThreatDomain(ctx context.Context, domain string) (*ThreatMatch, error) {
	return c.threat(ctx, "/api/v1/threat/domain/"+url.PathEscape(domain))
}

// ThreatHash looks up a file hash (md5/sha1/sha256).
func (c *Client) ThreatHash(ctx context.Context, hash string) (*ThreatMatch, error) {
	return c.threat(ctx, "/api/v1/threat/hash/"+url.PathEscape(hash))
}

// ThreatURL looks up a URL (server falls back to its domain on a miss).
func (c *Client) ThreatURL(ctx context.Context, u string) (*ThreatMatch, error) {
	return c.threat(ctx, "/api/v1/threat/url?u="+url.QueryEscape(u))
}

func (c *Client) threat(ctx context.Context, path string) (*ThreatMatch, error) {
	var out ThreatMatch
	if err := c.get(ctx, path, &out); err != nil {
		return nil, err
	}
	return &out, nil
}

func (c *Client) get(ctx context.Context, path string, out any) error {
	return c.do(ctx, http.MethodGet, path, nil, out)
}

func (c *Client) do(ctx context.Context, method, path string, body io.Reader, out any) error {
	req, err := http.NewRequestWithContext(ctx, method, c.baseURL+path, body)
	if err != nil {
		return err
	}
	req.Header.Set("User-Agent", userAgent)
	req.Header.Set("Accept", "application/json")
	if body != nil {
		req.Header.Set("Content-Type", "application/json")
	}
	if c.apiKey != "" {
		req.Header.Set("X-Api-Key", c.apiKey)
	}
	resp, err := c.http.Do(req)
	if err != nil {
		return err
	}
	defer resp.Body.Close()
	data, err := io.ReadAll(resp.Body)
	if err != nil {
		return err
	}
	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
		return &APIError{Status: resp.StatusCode, Message: apiErrMessage(data)}
	}
	if out == nil {
		return nil
	}
	if err := json.Unmarshal(data, out); err != nil {
		return fmt.Errorf("ipdata: decode response: %w", err)
	}
	return nil
}

func apiErrMessage(data []byte) string {
	var e struct {
		Error string `json:"error"`
	}
	if json.Unmarshal(data, &e) == nil && e.Error != "" {
		return e.Error
	}
	return string(data)
}