namedaemon 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9b70e727222e403e62dbe9a828c528a12f9c5d1cbf3d38de3da63771aad893ab
+  data.tar.gz: b655fe57923a4f5943347eae91560d0c06347514451cb7f49db1754a5384a10f
+SHA512:
+  metadata.gz: 80c4992228f3184dbf0f4d3bb5f3dac5620b17862d04b03eb35362326dbc8aa45043bd1bd38c749838bc29b634c9aeb73b78b7b9a391da9ebc6d37a86430f137
+  data.tar.gz: cb71947d098f6e396781f8a5d69359d1e53274cf426fffa973d016748c4f9241171ea6ebdae72cf7f958999c82f2950311186ffbc16b9785dd8983b117ed3267

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 0.1.0
+
+- First release: `NameDaemon::Client` and the `namedaemon` command for the public NameDaemon REST layer. Standard library only.
+- Optional `api_key:` (or `NAMEDAEMON_API_KEY`) sends a Pro+ or Business key as `X-ND-API-Key`.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Krasen Slavov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,84 @@
+# namedaemon (Ruby)
+
+Ruby client and command-line tool for [NameDaemon](https://namedaemon.com), a free set of .com domain tools: availability,
+brandability scores, name ideas, extension costs, domain health and more. No API key needed, standard library only.
+
+```
+gem install namedaemon
+```
+
+Needs Ruby 3.0 or newer. With Bundler: `gem "namedaemon"`.
+
+## Command line
+
+```
+namedaemon rate example
+namedaemon ideas nova 10
+namedaemon check nova novax mybrand
+namedaemon tld nova com io ai
+namedaemon tco io
+namedaemon health example
+namedaemon --json appraise example
+```
+
+`--json` prints the raw response.
+
+## Library
+
+```ruby
+require "namedaemon"
+
+nd = NameDaemon::Client.new
+
+r = nd.rate("example")
+puts "#{r["score"]} #{r["verdict"]}" # 95.5 Excellent
+
+ideas   = nd.ideas("nova", limit: 10)["ideas"]
+results = nd.check(%w[nova novax])["results"]
+cost    = nd.tco("io", years: 5)
+health  = nd.domain_health("example")
+```
+
+| Method | What it returns |
+|---|---|
+| `rate(name)` | brandability score, verdict, breakdown, tips |
+| `ideas(keyword, limit: nil)` | two-word .com ideas built around a keyword |
+| `check(names, verify: 0)` | zone status of up to 50 names, optional live checks |
+| `verify(names)` | live availability of up to 10 names |
+| `tld_check(label, tlds)` | one label across up to 12 extensions |
+| `tco(tld, **options)` | registration, renewal and total cost by registrar |
+| `hacks(word: ...)` | domain hacks such as `hack.er` |
+| `names(seeds, vibe: ..., count: ...)` | brand-name generator |
+| `domain_health(name)` | registration, DNS, email and blocklist checks |
+| `appraise(name, deep: false)` | strength report (no price) |
+| `handles(name)` | username availability on social platforms |
+| `web3(name)`, `screen(name)`, `hosting`, `trend(keyword)` | ENS/Solana names, name screening, hosting share, keyword trend |
+| `get(path, **params)`, `post(path, body)` | any other public route under `/wp-json/nd/v1/` |
+
+Every method returns the parsed JSON of the matching REST route (a Hash).
+
+### Errors and rate limits
+
+The public API is free and shared, so it limits each visitor to roughly 20 requests a minute. Heavier routes count for more.
+When the limit is hit the client raises `NameDaemon::RateLimitError` (with `retry_after` in seconds, 60 by default); pass
+`retries: 1` to wait and retry automatically. Other failures raise `NameDaemon::Error` with `status`, `code` and the server's message.
+
+```ruby
+nd = NameDaemon::Client.new(timeout: 20, retries: 1)
+begin
+  nd.rate("example")
+rescue NameDaemon::RateLimitError => e
+  puts e.retry_after
+end
+```
+
+Please keep usage reasonable. For bulk work, see the paid plan at https://namedaemon.com.
+
+## Links
+
+- Website and free tools: https://namedaemon.com
+- Issues: https://github.com/namedaemon/namedaemon-ruby/issues
+- Other languages: `npm install namedaemon`, `pip install namedaemon`, `composer require namedaemon/namedaemon`
+- Developer page: https://namedaemon.com/developers/
+
+MIT license.

data/exe/namedaemon

@@ -0,0 +1,70 @@
+#!/usr/bin/env ruby
+# Command line: namedaemon rate example
+require "json"
+require_relative "../lib/namedaemon"
+
+USAGE = <<~TEXT.freeze
+  usage: namedaemon [--json] COMMAND ARGS
+    rate NAME                brandability score for one name
+    ideas KEYWORD [LIMIT]    two-word .com ideas around a keyword
+    check NAME...            status of up to 50 names
+    verify NAME...           live availability of up to 10 names
+    tld LABEL TLD...         one label across several extensions
+    tco TLD                  cost of ownership for an extension
+    health NAME              DNS, email and registration health
+    appraise NAME            strength report (no price)
+    handles NAME             username availability on social platforms
+TEXT
+
+def pretty(cmd, r)
+  case cmd
+  when "rate"
+    line = "#{r["name"]}: #{r["score"].nil? ? "no score" : r["score"]} #{r["verdict"]}".strip
+    tips = r["tips"] || []
+    tips.empty? ? line : "#{line}\n- #{tips.join("\n- ")}"
+  when "ideas"
+    r["ideas"].map { |i| "#{i["domain"]}.com  #{i["score"]}" }.join("\n")
+  when "check", "verify", "tld"
+    r["results"].map { |x| "#{x["domain"]}  #{x["status"]}#{x["est_drop"].to_s.empty? ? "" : " (drops #{x["est_drop"]})"}" }.join("\n")
+  else
+    JSON.pretty_generate(r)
+  end
+end
+
+args = ARGV.dup
+json = !args.delete("--json").nil?
+if args.delete("--version")
+  puts "namedaemon #{NameDaemon::VERSION}"
+  exit 0
+end
+cmd = args.shift
+if cmd.nil? || %w[-h --help help].include?(cmd) || args.empty?
+  warn USAGE
+  exit(cmd.nil? || args.empty? ? 2 : 0)
+end
+
+nd = NameDaemon::Client.new
+begin
+  res =
+    case cmd
+    when "rate" then nd.rate(args[0])
+    when "ideas" then nd.ideas(args[0], limit: args[1]&.to_i)
+    when "check" then nd.check(args)
+    when "verify" then nd.verify(args)
+    when "tld" then nd.tld_check(args[0], args[1..])
+    when "tco" then nd.tco(args[0])
+    when "health" then nd.domain_health(args[0])
+    when "appraise" then nd.appraise(args[0])
+    when "handles" then nd.handles(args[0])
+    else
+      warn USAGE
+      exit 2
+    end
+rescue NameDaemon::RateLimitError => e
+  warn "Rate limit reached. Try again in about #{e.retry_after} seconds."
+  exit 1
+rescue NameDaemon::Error => e
+  warn "Error#{e.status.zero? ? "" : " #{e.status}"}: #{e.message}"
+  exit 1
+end
+puts json ? JSON.pretty_generate(res) : pretty(cmd, res)

data/lib/namedaemon/client.rb

@@ -0,0 +1,187 @@
+require "json"
+require "net/http"
+require "uri"
+require_relative "errors"
+require_relative "version"
+
+module NameDaemon
+  DEFAULT_BASE_URL = "https://namedaemon.com/wp-json/nd/v1".freeze
+
+  # Client for the public NameDaemon REST layer. Standard library only (Net::HTTP).
+  #
+  #   nd = NameDaemon::Client.new
+  #   nd.rate("example")["score"] # => 95.5
+  class Client
+    attr_reader :base_url, :timeout, :retries, :user_agent
+
+    # transport: optional callable (method, uri, headers, body, timeout) => [status, headers, body] with lower-case header names.
+    def initialize(base_url: DEFAULT_BASE_URL, timeout: 20, retries: 0, user_agent: nil, api_key: nil, transport: nil, sleeper: nil)
+      @base_url = base_url.sub(%r{/+\z}, "")
+      @timeout = timeout
+      @retries = retries
+      @user_agent = user_agent || "namedaemon-rb/#{VERSION}"
+      # A Pro+ or Business API key (X-ND-API-Key); defaults to the NAMEDAEMON_API_KEY environment variable.
+      @api_key = api_key || ENV.fetch("NAMEDAEMON_API_KEY", "")
+      @transport = transport || method(:net_http)
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+    end
+
+    # Any public GET route, e.g. nd.get("trend", keyword: "ai").
+    def get(path, **params)
+      request("GET", path, params: params)
+    end
+
+    # Any public POST route with a JSON body.
+    def post(path, body)
+      request("POST", path, body: body)
+    end
+
+    # Brandability score and breakdown for one name (4-24 letters).
+    def rate(name)
+      get("rate", name: name)
+    end
+
+    # Two-word .com ideas built around a keyword (3-14 letters).
+    def ideas(q, limit: nil)
+      get("ideas", q: q, limit: limit)
+    end
+
+    # Live availability of up to 10 names.
+    def verify(domains)
+      post("verify", { domains: Array(domains) })
+    end
+
+    # Zone status of up to 50 names, with optional live checks (0-10).
+    def check(domains, verify: 0)
+      post("check", { domains: Array(domains), verify: verify })
+    end
+
+    # One label across up to 12 extensions.
+    def tld_check(label, tlds)
+      get("tld-check", label: label, tlds: tlds)
+    end
+
+    # Cost of ownership for an extension, or a ranking with q / scope / sort / limit.
+    def tco(tld = nil, **options)
+      get("tco", tld: tld, **options)
+    end
+
+    # Domain hacks (for example hack.er). Pass word: or keyword:, and mode:.
+    def hacks(**options)
+      get("hacks", **options)
+    end
+
+    # Brand-name generator: seeds plus vibe, min_len, max_len, count, variation, hide_taken.
+    def names(seeds, **options)
+      get("names", seeds: seeds, **options)
+    end
+
+    # Registration, DNS, email and blocklist checks for a .com label.
+    def domain_health(name)
+      get("domain-health", name: name)
+    end
+
+    # Strength report for a name (no price).
+    def appraise(name, deep: false)
+      get("appraise", name: name, deep: deep ? true : nil)
+    end
+
+    # Username availability on social platforms.
+    def handles(name)
+      get("handles", name: name)
+    end
+
+    # ENS and Solana name availability.
+    def web3(name)
+      get("web3", name: name)
+    end
+
+    # Name screening: unwanted meanings in other languages.
+    def screen(name)
+      get("screen", name: name)
+    end
+
+    # Hosting provider ranking (mode: top, provider or domain).
+    def hosting(mode: nil, q: nil)
+      get("hosting", mode: mode, q: q)
+    end
+
+    # Daily size history for a keyword in the .com zone.
+    def trend(keyword)
+      get("trend", keyword: keyword)
+    end
+
+    private
+
+    # Drops nil and empty values; booleans become "true" / "false" and lists become comma-separated.
+    def clean(params)
+      params.each_with_object({}) do |(key, value), out|
+        next if value.nil? || value == ""
+
+        value = value.join(",") if value.is_a?(Array)
+        out[key.to_s] = value.to_s
+      end
+    end
+
+    def request(verb, path, params: {}, body: nil)
+      uri = URI("#{@base_url}/#{path.to_s.sub(%r{\A/+}, "")}")
+      query = URI.encode_www_form(clean(params))
+      uri.query = query unless query.empty?
+      headers = { "accept" => "application/json", "user-agent" => @user_agent }
+      headers["x-nd-api-key"] = @api_key unless @api_key.to_s.empty?
+      payload = nil
+      unless body.nil?
+        payload = JSON.generate(body)
+        headers["content-type"] = "application/json"
+      end
+
+      attempt = 0
+      loop do
+        begin
+          status, response_headers, raw = @transport.call(verb, uri, headers, payload, @timeout)
+        rescue Error
+          raise
+        rescue StandardError => e
+          raise Error, "Network error: #{e.message}"
+        end
+
+        parsed = begin
+          raw.to_s.empty? ? nil : JSON.parse(raw)
+        rescue JSON::ParserError
+          nil
+        end
+
+        if status.between?(200, 299)
+          raise Error.new("Response was not JSON", status: status) if parsed.nil?
+
+          return parsed
+        end
+
+        message = (parsed.is_a?(Hash) && parsed["message"]) || "HTTP #{status}"
+        code = parsed.is_a?(Hash) ? parsed["code"].to_s : ""
+        if status == 429
+          retry_after = response_headers["retry-after"].to_i
+          retry_after = 60 if retry_after <= 0
+          if attempt < @retries
+            attempt += 1
+            @sleeper.call([retry_after, 60].min)
+            next
+          end
+          raise RateLimitError.new(message, retry_after: retry_after, code: code, body: parsed)
+        end
+        raise Error.new(message, status: status, code: code, body: parsed)
+      end
+    end
+
+    def net_http(verb, uri, headers, body, timeout)
+      klass = verb == "POST" ? Net::HTTP::Post : Net::HTTP::Get
+      req = klass.new(uri)
+      headers.each { |k, v| req[k] = v }
+      req.body = body if body
+      res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: timeout, read_timeout: timeout) do |http|
+        http.request(req)
+      end
+      [res.code.to_i, res.each_header.to_h.transform_keys(&:downcase), res.body.to_s]
+    end
+  end
+end

data/lib/namedaemon/errors.rb

@@ -0,0 +1,23 @@
+module NameDaemon
+  # Any failed request. +status+ is 0 for network errors.
+  class Error < StandardError
+    attr_reader :status, :code, :body
+
+    def initialize(message, status: 0, code: "", body: nil)
+      super(message)
+      @status = status
+      @code = code
+      @body = body
+    end
+  end
+
+  # HTTP 429: the shared limit was hit. +retry_after+ is in seconds.
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(message, retry_after: 60, code: "", body: nil)
+      super(message, status: 429, code: code, body: body)
+      @retry_after = retry_after
+    end
+  end
+end

data/lib/namedaemon/version.rb

@@ -0,0 +1,3 @@
+module NameDaemon
+  VERSION = "0.1.0"
+end

data/lib/namedaemon.rb

@@ -0,0 +1,3 @@
+require_relative "namedaemon/version"
+require_relative "namedaemon/errors"
+require_relative "namedaemon/client"

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: namedaemon
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Krasen Slavov
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-10-20 00:00:00.000000000 Z
+dependencies: []
+description: 'Client for the public NameDaemon REST layer (https://namedaemon.com):
+  domain availability, brandability scores, two-word name ideas, extension costs,
+  domain health and more. Standard library only, no API key needed.'
+email:
+executables:
+- namedaemon
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- exe/namedaemon
+- lib/namedaemon.rb
+- lib/namedaemon/client.rb
+- lib/namedaemon/errors.rb
+- lib/namedaemon/version.rb
+homepage: https://namedaemon.com/developers/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://namedaemon.com/developers/
+  source_code_uri: https://github.com/namedaemon/namedaemon-ruby
+  bug_tracker_uri: https://github.com/namedaemon/namedaemon-ruby/issues
+  changelog_uri: https://github.com/namedaemon/namedaemon-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: 'Ruby client and CLI for NameDaemon: .com domain availability, brandability
+  scores, name ideas and domain health.'
+test_files: []