@hasna/domains 0.0.23 → 0.0.24

package/README.md

@@ -1,11 +1,17 @@
 # @hasna/domains
 
-Domain portfolio and DNS management for AI agents — CLI + MCP server with SQLite.
+Domain portfolio, registrar, marketplace, and DNS management for AI agents — CLI + MCP server with SQLite.
 
 ## Features
 
-- **Domain portfolio management** — track registrar, expiry, SSL, nameservers, status
+- **Domain portfolio management** — track registrar, expiry, SSL, nameservers, pricing, lifecycle status, and notes
+- **Registrar sync and purchase flows** — direct Route 53 and Namecheap registration plus GoDaddy and Brandsight provider surfaces through a shared provider registry
+- **Nameserver delegation** — Route 53 and Namecheap adapters can update registrar nameservers when the provider API supports it
+- **DNS provider management** — create or reuse Cloudflare or Route 53 zones and manage DNS records through the DNS provider layer
 - **DNS record CRUD** — A, AAAA, CNAME, MX, TXT, NS, SRV records
+- **Sedo marketplace tools** — search, portfolio/listing management, blacklist checks, and recorded Sedo purchases
+- **AWS diagnostics** — sync Route 53 registered domains and hosted zones without printing secret values
+- **Credential diagnostics** — redacted checks for Route 53, Cloudflare, Namecheap, GoDaddy, Brandsight, and Sedo
 - **Expiry alerts** — set alerts for domain expiry and SSL certificate expiry
 - **WHOIS lookup** — query and store registrar/expiry info from WHOIS
 - **SSL certificate check** — verify SSL issuer and expiry
@@ -14,10 +20,9 @@ Domain portfolio and DNS management for AI agents — CLI + MCP server with SQLi
 - **Subdomain discovery** — via crt.sh certificate transparency logs
 - **DNS validation** — detect CNAME conflicts, missing MX, and more
 - **Portfolio export** — CSV or JSON with all domain data
-- **Registrar sync** — Namecheap and GoDaddy integration
 - **Brand monitoring** — typosquat/threat detection via Brandsight API
-- **MCP server** — full Model Context Protocol support for AI agents
-- **Interactive TUI** — browse your portfolio in the terminal with `domains interactive`
+- **MCP server** — Model Context Protocol support for AI agents
+- **Interactive TUI** — browse the portfolio in the terminal with `domains interactive`
 
 ## Installation
 
@@ -25,36 +30,98 @@ Domain portfolio and DNS management for AI agents — CLI + MCP server with SQLi
 npm install -g @hasna/domains
 ```
 
-Data is stored at `~/.hasna/domains/domains.db`. Override with `HASNA_DOMAINS_DIR` or `DOMAINS_DIR` env var.
+Data is stored in the local domains data directory (`$XDG_DATA_HOME/open-domains` or `~/.local/share/open-domains` for new installs; existing legacy installs continue using their current directory). Override with `DOMAINS_DB_PATH`, `DOMAINS_DIR`, or the legacy `HASNA_DOMAINS_DB_PATH` / `HASNA_DOMAINS_DIR` names.
+
+## Quick Start
+
+```bash
+# Set defaults used by availability, buy, setup, DNS, and doctor commands
+domains config set default-registrar route53
+domains config set default-dns cloudflare
+domains config set purchase-aws-profile production-domains
+
+# Add registrant contact defaults used by registrar purchase APIs
+domains config set contact.first_name Jane
+domains config set contact.last_name Example
+domains config set contact.email jane@example.com
+domains config set contact.phone +1.5555555555
+domains config set contact.address_line_1 "1 Main St"
+domains config set contact.city "New York"
+domains config set contact.state NY
+domains config set contact.country_code US
+domains config set contact.zip_code 10001
+
+# Check local health without printing secrets
+domains doctor
+```
+
+## Provider Matrix
+
+| Provider | Type | Availability | Buy/Register | Renew | Nameservers/DNS | Notes |
+|----------|------|--------------|--------------|-------|-----------------|-------|
+| `route53` | registrar + DNS | yes | yes | no | nameservers + Route 53 hosted zones | Primary self-serve registration path. Use `AWS_PROFILE` or AWS keys. |
+| `namecheap` | registrar + DNS | yes | yes | yes | nameservers + Namecheap DNS records | Requires Namecheap API access and whitelisted client IP. |
+| `godaddy` | registrar + DNS | gated | no direct CLI purchase | gated | DNS records when API access qualifies | Availability remains threshold-gated; DNS/domain management is available for qualifying accounts. |
+| `brandsight` | registrar + DNS | yes | gated by contract | yes when contract allows | nameservers + DNS records | GoDaddy Corporate Domains / Brandsight v2 API; enterprise-contract-only. |
+| `cloudflare` | DNS + inventory | no | no | no | DNS zones and records | Preferred DNS provider; zone inventory syncs domains but does not prove registrar ownership. |
+| `sedo` | marketplace | marketplace search/status | recorded purchase only | no | no | Sedo is marketplace/listing/portfolio, not registrar DNS in this CLI. |
 
 ## CLI Usage
 
 ```bash
-# Interactive portfolio browser (Ink TUI)
+# Interactive portfolio browser
 domains interactive
 domains interactive --status active
-```
-domains add --name example.com --registrar Namecheap --expires-at 2025-01-01
-domains list
-domains list --status active --registrar Namecheap
-domains get <id>
-domains update <id> --notes "renewed"
-domains delete <id>
-domains search example
-domains stats
+
+# Portfolio management
+domains domain add --name example.com --registrar Namecheap --expires-at 2027-01-01
+domains domain list
+domains domain list --status active --registrar Namecheap
+domains domain get example.com
+domains domain update <id> --notes "renewed"
+domains domain delete <id>
+domains domain search example
+domains domain stats
 
 # Expiry monitoring
-domains expiring --days 30
-domains ssl --days 30
+domains domain expiring --days 30
+domains ssl expiring --days 30
 
 # WHOIS / SSL checks
-domains whois example.com
-domains ssl-check example.com
-domains check-all
+domains domain whois example.com
+domains ssl check example.com
+domains domain check example.com example.net
 
 # Portfolio export
-domains export --format csv --output portfolio.csv
-domains export --format json
+domains domain export --format csv > portfolio.csv
+domains domain export --format json
+
+# Provider registry and diagnostics
+domains providers
+domains provider list
+domains provider test route53
+domains provider test cloudflare
+domains doctor
+
+# Registrar sync
+domains sync --provider route53
+domains sync --provider cloudflare
+domains sync --provider namecheap
+domains sync --provider godaddy
+domains sync --provider brandsight
+domains sync --all
+
+# Availability and renewals
+domains check example.com
+domains check --provider route53 example.com
+domains check --provider namecheap example.com
+domains renew example.com --provider namecheap --years 1
+
+# Purchases and setup
+domains domain buy example.com --provider route53 --wait
+domains domain buy example.com --provider namecheap --wait
+domains domain buy premium.example --registrar sedo --price 2500 --expires 2027-01-01
+domains domain setup example.com --registrar route53 --dns cloudflare --wait
 
 # DNS record management
 domains dns list <domain-id>
@@ -66,24 +133,17 @@ domains dns export <domain-id>
 domains dns import <domain-id> --file zone.txt
 domains dns discover-subdomains example.com
 domains dns validate <domain-id>
-
-# Alerts
-domains alert set --domain <id> --type expiry --days-before 30
-domains alert list <domain-id>
-domains alert remove <alert-id>
-
-# Registrar integration
-domains providers
-domains sync --provider namecheap
-domains sync --provider godaddy
-domains sync --all
-domains renew example.com --provider namecheap
-
-# Availability checks — pick the registrar with --provider
-domains check example.com                     # default registrar (config default-registrar, else namecheap)
-domains check --provider route53 example.com  # AWS Route 53 availability
-domains check --provider godaddy example.com
-domains r53 check example.com                  # Route 53-specific subcommand (same backend)
+domains dns pull example.com --provider cloudflare
+domains dns push <domain-id> --provider cloudflare
+
+# Sedo marketplace
+domains sedo search example
+domains sedo status example.com
+domains sedo portfolio --limit 25
+domains sedo add example.com --price 2500
+domains sedo edit example.com --price 3000
+domains sedo remove example.com
+domains sedo buy example.com --price 2500 --order-id SEDO-ORDER-ID
 
 # Brand monitoring
 domains monitor mybrand
@@ -91,12 +151,33 @@ domains similar example.com
 domains threats example.com
 ```
 
-> **Prefer the `domains` CLI over raw `aws` commands.** For Route 53 availability,
-> registration status, and DNS, use `domains check --provider route53`,
-> `domains r53 status`, and `domains dns …` instead of `aws route53domains …` /
-> `aws route53 …`. The CLI applies the configured purchase profile, records the
-> result in the local portfolio DB, and works the same across registrars — raw
-> `aws` calls bypass all of that.
+Prefer the `domains` CLI over raw registrar CLIs for Route 53 availability, registration status, local portfolio updates, and DNS delegation. The CLI applies configured defaults, records outcomes in the local portfolio DB, and keeps behavior consistent across providers.
+
+## AWS Domain Discovery
+
+```bash
+# Sync registered domains and hosted zones from specific AWS profiles
+AWS_PROFILE=production-domains domains sync --provider route53
+AWS_PROFILE=shared-dns domains sync --provider route53
+
+# Check all configured providers and redacted credential status
+domains providers --json
+domains doctor --json
+```
+
+Route 53 sync imports registered domains when the selected AWS account permits `route53domains:ListDomains`, and hosted zones when the account permits Route 53 hosted-zone reads. Domain-looking names from unrelated systems such as SSM parameters or Secrets Manager should only be imported after review because they do not prove registrar ownership.
+
+## Storage Sync
+
+Set one of these environment variables to sync with a remote PostgreSQL storage database:
+
+```bash
+export DOMAINS_DATABASE_URL="postgres://..."
+
+domains storage status
+domains storage push
+domains storage pull
+```
 
 ## MCP Server
 
@@ -126,8 +207,8 @@ domains-mcp --http --port 8814
 MCP_HTTP=1 MCP_HTTP_PORT=8814 domains-mcp
 ```
 
-- `GET /health` → `{"status":"ok","name":"domains"}`
-- `POST /mcp` — Streamable HTTP MCP endpoint
+- `GET /health` returns `{"status":"ok","name":"domains"}`
+- `POST /mcp` is the Streamable HTTP MCP endpoint
 
 Stdio remains the default transport for gradual rollout.
 
@@ -135,15 +216,29 @@ Stdio remains the default transport for gradual rollout.
 
 | Variable | Description |
 |----------|-------------|
+| `DOMAINS_DB_PATH` | Override database file path |
+| `HASNA_DOMAINS_DB_PATH` | Override database file path |
+| `DOMAINS_CONFIG_PATH` | Override config file path |
+| `DOMAINS_CONFIG_DIR` | Override config directory |
 | `HASNA_DOMAINS_DIR` | Override database directory |
-| `DOMAINS_DIR` | Override database directory (fallback) |
+| `DOMAINS_DIR` | Override database directory fallback |
+| `DOMAINS_DATABASE_URL` | Remote storage PostgreSQL database URL |
+| `HASNA_DOMAINS_DATABASE_URL` | Legacy remote storage PostgreSQL database URL fallback |
+| `DOMAINS_STORAGE_MODE` | Storage mode: `local`, `remote`, or `hybrid` |
+| `HASNA_DOMAINS_STORAGE_MODE` | Legacy storage mode fallback |
+| `AWS_PROFILE` | AWS profile for Route 53 Domains and hosted zones |
+| `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN` | AWS credential fallback |
+| `DOMAINS_PURCHASE_AWS_PROFILE` | Purchase profile fallback when config has no `purchase_aws_profile` |
+| `CLOUDFLARE_API_TOKEN` | Cloudflare API token |
+| `CLOUDFLARE_API_KEY`, `CLOUDFLARE_EMAIL` | Cloudflare global key fallback |
+| `CLOUDFLARE_ACCOUNT_ID` | Cloudflare account ID for zone creation |
 | `NAMECHEAP_API_KEY` | Namecheap API key |
 | `NAMECHEAP_USERNAME` | Namecheap account username |
 | `NAMECHEAP_CLIENT_IP` | Namecheap whitelisted IP |
 | `NAMECHEAP_SANDBOX` | Use Namecheap sandbox API |
-| `GODADDY_API_KEY` | GoDaddy API key |
-| `GODADDY_API_SECRET` | GoDaddy API secret |
-| `BRANDSIGHT_API_KEY` | Brandsight API key |
+| `GODADDY_API_KEY`, `GODADDY_API_SECRET` | GoDaddy API credentials |
+| `BRANDSIGHT_API_KEY`, `BRANDSIGHT_API_SECRET`, `BRANDSIGHT_CUSTOMER_ID` | Brandsight / GoDaddy Corporate Domains credentials |
+| `SEDO_PARTNER_ID`, `SEDO_API_KEY`, `SEDO_USERNAME`, `SEDO_PASSWORD` | Sedo marketplace API credentials |
 
 ## License
 

package/dist/cli/commands/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkBzC,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAyD7D"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmBzC,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA0D7D"}

package/dist/cli/commands/domain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"domain.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/domain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkDzC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA8vB5D"}
+{"version":3,"file":"domain.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/domain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA8DzC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA00B5D"}

package/dist/cli/commands/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGzC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAuJ9D"}
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQzC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA4L9D"}

package/dist/cli/commands/providers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/providers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAuBzC,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAuM/D"}
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/providers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAoDzC,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA2J/D"}

package/dist/cli/commands/storage.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+export declare function registerStorageCommand(program: Command): void;
+//# sourceMappingURL=storage.d.ts.map

package/dist/cli/commands/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA2GzC,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAE7D"}

package/dist/cli/commands/wallet.d.ts

@@ -1,8 +1,8 @@
 /**
  * Wallet payment integration for domain purchases
  *
- * Uses @hasna/wallets virtual cards to pay for domain registrations,
- * renewals, and marketplace purchases (Sedo, etc.)
+ * Uses an optional wallet module to pay for domain registrations,
+ * renewals, and marketplace purchases (Sedo, etc.).
  */
 import type { Command } from "commander";
 export interface WalletCard {

package/dist/cli/commands/wallet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wallet.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/wallet.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIzC,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AA2BD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAyL5D"}
+{"version":3,"file":"wallet.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/wallet.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIzC,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAwCD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAyL5D"}