# Porkbun Domain Price Checker

A Python CLI tool for bulk querying domain pricing information from the Porkbun API.

## Features

- Bulk domain price queries from a file
- **Domain availability checking** - Shows if domains are available for registration
- JSON Lines output format
- SQLite caching to avoid duplicate API calls
- **Progress bars by default** - Visual feedback for all queries (disable with `-q`)
- Aggressive 429 retry handling
- Async implementation for performance
- Multiple credential sources (CLI, env vars, config file)
- Debug mode with detailed HTTP request/response logging
- Single domain queries with `-d` flag

## Installation

```bash
uv pip install -e .
```

## Configuration

API credentials can be provided in three ways (in order of priority):

### 1. Command Line Arguments
```bash
porkbun test_domains.txt --api-key pk1_... --secret-key sk1_...
```

### 2. Environment Variables
```bash
export PORKBUN_API_KEY=pk1_...
export PORKBUN_SECRET_KEY=sk1_...
porkbun test_domains.txt
```

### 3. Config File
Create `~/.config/porkbun/cli.json`:
```json
{
  "api_key": "pk1_...",
  "secret_key": "sk1_..."
}
```

Then simply run:
```bash
porkbun test_domains.txt
```

## Usage

### Query from File
```bash
# Basic usage (shows progress bars by default)
porkbun test_domains.txt

# Quiet mode (disable progress bars, JSON only)
porkbun test_domains.txt --quiet
porkbun test_domains.txt -q

# Refresh data from API and update cache
porkbun test_domains.txt --refresh

# Clear cache before running
porkbun test_domains.txt --clear-cache

# Debug mode (shows full HTTP requests/responses and status)
porkbun test_domains.txt --debug
```

### Query Single/Multiple Domains
```bash
# Single domain (shows progress bar by default)
porkbun -d example.com
porkbun --domain example.com

# Multiple domains (shows progress for each)
porkbun -d example.com -d test.net -d sample.org

# Quiet mode for clean JSON output (useful for piping)
porkbun -d example.com -q
echo "example.com\ntest.net" | porkbun --quiet

# Combined with other flags
porkbun -d example.com --refresh --debug
```

## Debug Mode

When `--debug` is specified, the tool shows:

1. **Status messages** (to stderr):
   - `[API] Fetching pricing for domain.com...` - When making API calls
   - `[CACHE] Using cached result for domain.com` - When using cached data

2. **Full HTTP details** (to stderr):
   - Complete request headers and payload
   - Complete response headers and body
   - Rate limit retry information

**Example output:**
```bash
$ porkbun -d example.com -d test.net --debug

[API] Fetching pricing for example.com...
================================================================================
DEBUG: REQUEST
URL: POST https://api.porkbun.com/api/json/v3/pricing/get
Headers: {'accept': '*/*', 'accept-encoding': 'gzip, deflate', ...}
Payload: {"apikey": "pk1_...", "secretapikey": "sk1_..."}
================================================================================
DEBUG: RESPONSE
Status: 200 OK
Headers: {'date': '...', 'content-type': 'application/json', ...}
Body: {"status":"SUCCESS","pricing":{...}}
================================================================================
{"domain": "example.com", "tld": "com", "pricing": {"registration": "11.08", ...}}

[CACHE] Using cached result for test.net
{"domain": "test.net", "tld": "net", "pricing": {"registration": "12.52", ...}}
```

**Note:** JSON results always go to stdout, debug/status messages go to stderr for easy separation.

## Progress Bars

**By default**, the tool shows real-time progress bars for each domain being processed. Use `-q` or `--quiet` to disable this for clean JSON-only output.

**Features:**
- Overall progress bar showing total completion
- Individual progress bars for each domain
- Color-coded status indicators:
  - 🟡 Yellow: In progress (checking cache or fetching from API)
  - 🟢 Green: Complete or from cache
  - 🔴 Red: Error occurred
- Shows whether data came from cache or API

**Example output (default):**
```
  Processing domains...      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%
  example.com - ✓ From cache ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%
  test.net - ✓ Complete      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%
  sample.org - ✓ Complete    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%
```

**Disable progress bars for piping:**
```bash
# Clean JSON output only (no progress bars)
porkbun domains.txt -q > results.jsonl
porkbun -d example.com --quiet | jq .
```

**When to use quiet mode:**
- Piping output to other tools
- Scripting and automation
- When you only want the JSON output
- Redirecting to files

## Input Format

Create a text file with one domain per line:

```
example.com
google.com
test.net
```

## Output Format

JSON Lines format with pricing and availability information:

```json
{"domain": "example.com", "tld": "com", "pricing": {"registration": "11.08", "renewal": "11.08", "transfer": "11.08", "coupons": []}, "available": false}
{"domain": "myuniquedomain.com", "tld": "com", "pricing": {"registration": "11.08", "renewal": "11.08", "transfer": "11.08", "coupons": []}, "available": true}
```

### Fields:
- `domain` - The queried domain name
- `tld` - Top-level domain (e.g., "com", "net", "org")
- `pricing` - Pricing information from Porkbun
  - `registration` - Price to register the domain
  - `renewal` - Annual renewal price
  - `transfer` - Price to transfer the domain
  - `coupons` - Array of available coupons
- `available` - Boolean indicating if the domain is available for registration at Porkbun
  - `true` - Domain is available
  - `false` - Domain is taken
  - `null` - Availability check failed
- `premium` - (Optional) Set to `true` if domain is premium pricing

## Cache

Pricing and availability data is cached in `~/.local/share/porkbun/cache.sqlite` to avoid redundant API calls and speed up repeated queries.

### Cache Behavior:
- **Default**: Uses cached data when available (fast, no API calls)
- **`--refresh`**: Fetches fresh data from API and updates the cache for queried domains
- **`--clear-cache`**: Deletes all cached data before running

### Example Workflow:
```bash
# First run - queries API and caches results
porkbun -d example.com

# Second run - uses cached data (instant)
porkbun -d example.com

# Update cached data - fetches fresh data and updates cache
porkbun -d example.com --refresh

# Future runs use the updated cache
porkbun -d example.com
```

The cache stores both pricing and availability information, so using `--refresh` is useful when you want to check if previously unavailable domains have become available.