ipdata

#!/usr/bin/env bash
#
# ipdata - official Bash CLI for the ipdata.info API
# https://github.com/IPDataInfo/ipdata-bash
#
# A thin curl+jq wrapper: every subcommand prints the raw API JSON to stdout
# so it can be piped straight into jq or any other tool.
set -euo pipefail

VERSION="0.1.0"
DEFAULT_HOST="https://ipdata.info"
PRO_HOST="https://pro.ipdata.info"
USER_AGENT="ipdata-bash/${VERSION}"
TIMEOUT="${IPDATA_TIMEOUT:-10}"

API_KEY="${IPDATA_API_KEY:-}"
HOST="${IPDATA_HOST:-}"

# ---------------------------------------------------------------------------
# helpers
# ---------------------------------------------------------------------------

err() {
  printf 'ipdata: %s\n' "$*" >&2
}

die() {
  err "$*"
  exit 1
}

check_deps() {
  command -v curl >/dev/null 2>&1 || die "curl is required but not installed. Install curl and try again."
  command -v jq >/dev/null 2>&1 || die "jq is required but not installed. Install jq and try again."
}

usage() {
  cat <<'EOF'
ipdata - official Bash CLI for the ipdata.info API

USAGE:
  ipdata <command> [args] [flags]

COMMANDS:
  lookup [ip]                Full geolocation record (own IP if omitted)
  geo <ip>                   Geo subset (city/region/country/lat/lon/tz)
  asn <ip>                   ASN + ISP/registry for an IP
  batch <ip...>              Many IPs at once (requires a paid API key)
  asn-detail <number>        ASN detail incl. prefixes
  asn-whois-history <number> ASN whois history
  asn-changes                ASN change feed
  threat-domain <domain>     Threat-intel lookup for a domain
  threat-hash <hash>         Threat-intel lookup for a file hash (md5/sha1/sha256)
  threat-url <url>           Threat-intel lookup for a URL
  version                    Print CLI version
  help                       Show this help

FLAGS:
  --key <key>       API key (overrides IPDATA_API_KEY)
  --host <host>     API host (overrides IPDATA_HOST, default https://ipdata.info)

ENVIRONMENT:
  IPDATA_API_KEY     API key sent as the X-Api-Key header
  IPDATA_HOST        API host override
  IPDATA_TIMEOUT     Request timeout in seconds (default 10)

EXAMPLES:
  ipdata lookup 8.8.8.8
  ipdata lookup
  ipdata geo 1.1.1.1 | jq '.city'
  IPDATA_API_KEY=xxxx ipdata batch 8.8.8.8 1.1.1.1
  ipdata threat-domain example.com

Free tier: https://ipdata.info, 50 req/min, no key required.
Get a free API key: https://ipdata.info/register
EOF
}

# Resolve the effective host: if a key is set and the host is still the
# default (i.e. the caller did not explicitly pick a host), prefer the paid
# host so keyed requests get the higher-limit tier automatically.
resolve_host() {
  if [[ -n "$HOST" ]]; then
    printf '%s' "$HOST"
  elif [[ -n "$API_KEY" ]]; then
    printf '%s' "$PRO_HOST"
  else
    printf '%s' "$DEFAULT_HOST"
  fi
}

# URL-encode a string using jq (avoids depending on curl --data-urlencode
# quirks across platforms).
urlencode() {
  jq -rn --arg s "$1" '$s|@uri'
}

# Perform an HTTP request against the API.
#   request <method> <path> [body]
# Prints response body to stdout on 2xx. On non-2xx, prints the API's
# `.error` message to stderr and returns a non-zero exit code (the HTTP
# status code, capped at 255).
request() {
  local method="$1" path="$2" body="${3:-}"
  local base
  base="$(resolve_host)"
  local url="${base}${path}"

  local -a curl_args=(
    --silent --show-error --location
    --max-time "$TIMEOUT"
    --request "$method"
    --header "User-Agent: ${USER_AGENT}"
    --header "Accept: application/json"
    --write-out '\n%{http_code}'
  )

  if [[ -n "$API_KEY" ]]; then
    curl_args+=(--header "X-Api-Key: ${API_KEY}")
  fi

  if [[ -n "$body" ]]; then
    curl_args+=(--header "Content-Type: application/json" --data "$body")
  fi

  local response http_code response_body
  if ! response="$(curl "${curl_args[@]}" "$url" 2>&1)"; then
    die "request to ${url} failed: ${response}"
  fi

  http_code="${response##*$'\n'}"
  response_body="${response%$'\n'*}"

  if [[ "$http_code" -ge 200 && "$http_code" -lt 300 ]]; then
    printf '%s\n' "$response_body"
    return 0
  fi

  local message
  message="$(printf '%s' "$response_body" | jq -r '.error // empty' 2>/dev/null || true)"
  if [[ -z "$message" ]]; then
    message="$response_body"
  fi
  err "HTTP ${http_code}: ${message}"

  local exit_code="$http_code"
  if [[ "$exit_code" -lt 1 || "$exit_code" -gt 255 ]]; then
    exit_code=1
  fi
  return "$exit_code"
}

require_arg() {
  local name="$1" value="${2:-}"
  if [[ -z "$value" ]]; then
    die "missing required argument: ${name}"
  fi
}

# ---------------------------------------------------------------------------
# subcommands
# ---------------------------------------------------------------------------

cmd_lookup() {
  local ip="${1:-}"
  request GET "/json/${ip}"
}

cmd_geo() {
  local ip="${1:-}"
  require_arg "ip" "$ip"
  request GET "/api/v1/${ip}/geo"
}

cmd_asn() {
  local ip="${1:-}"
  require_arg "ip" "$ip"
  request GET "/api/v1/${ip}/asn"
}

cmd_batch() {
  if [[ "$#" -eq 0 ]]; then
    die "missing required argument: at least one ip"
  fi
  local body
  body="$(printf '%s\n' "$@" | jq -R . | jq -s .)"
  request POST "/api/v1/batch" "$body"
}

cmd_asn_detail() {
  local number="${1:-}"
  require_arg "number" "$number"
  request GET "/api/v1/asn/${number}"
}

cmd_asn_whois_history() {
  local number="${1:-}"
  require_arg "number" "$number"
  request GET "/api/v1/asn/${number}/whois-history"
}

cmd_asn_changes() {
  request GET "/api/v1/asn-changes"
}

cmd_threat_domain() {
  local domain="${1:-}"
  require_arg "domain" "$domain"
  request GET "/api/v1/threat/domain/${domain}"
}

cmd_threat_hash() {
  local hash="${1:-}"
  require_arg "hash" "$hash"
  request GET "/api/v1/threat/hash/${hash}"
}

cmd_threat_url() {
  local url="${1:-}"
  require_arg "url" "$url"
  local encoded
  encoded="$(urlencode "$url")"
  request GET "/api/v1/threat/url?u=${encoded}"
}

# ---------------------------------------------------------------------------
# argument parsing
# ---------------------------------------------------------------------------

main() {
  local -a positional=()
  local command=""

  while [[ "$#" -gt 0 ]]; do
    case "$1" in
      --key)
        [[ "$#" -ge 2 ]] || die "--key requires a value"
        API_KEY="$2"
        shift 2
        ;;
      --key=*)
        API_KEY="${1#--key=}"
        shift
        ;;
      --host)
        [[ "$#" -ge 2 ]] || die "--host requires a value"
        HOST="$2"
        shift 2
        ;;
      --host=*)
        HOST="${1#--host=}"
        shift
        ;;
      -h|--help)
        if [[ -z "$command" ]]; then
          usage
          exit 0
        fi
        positional+=("$1")
        shift
        ;;
      *)
        if [[ -z "$command" ]]; then
          command="$1"
        else
          positional+=("$1")
        fi
        shift
        ;;
    esac
  done

  if [[ -z "$command" ]]; then
    usage
    exit 1
  fi

  check_deps

  case "$command" in
    lookup) cmd_lookup "${positional[@]:-}" ;;
    geo) cmd_geo "${positional[@]:-}" ;;
    asn) cmd_asn "${positional[@]:-}" ;;
    batch) cmd_batch "${positional[@]:-}" ;;
    asn-detail) cmd_asn_detail "${positional[@]:-}" ;;
    asn-whois-history) cmd_asn_whois_history "${positional[@]:-}" ;;
    asn-changes) cmd_asn_changes ;;
    threat-domain) cmd_threat_domain "${positional[@]:-}" ;;
    threat-hash) cmd_threat_hash "${positional[@]:-}" ;;
    threat-url) cmd_threat_url "${positional[@]:-}" ;;
    version|--version) printf 'ipdata-bash %s\n' "$VERSION" ;;
    help|--help) usage ;;
    *) die "unknown command: ${command} (run 'ipdata help' for usage)" ;;
  esac
}

main "$@"