nondisposable 0.3.0 → 0.4.0

data/lib/nondisposable.rb

@@ -2,8 +2,11 @@
 
 require_relative "nondisposable/version"
 require_relative "nondisposable/engine"
+require_relative "nondisposable/tld"
+require_relative "nondisposable/suggestion"
 require_relative "nondisposable/email_validator"
 require_relative "nondisposable/domain_list_updater"
+require_relative "nondisposable/tld_list_updater"
 
 module Nondisposable
   class Error < StandardError; end
@@ -30,6 +33,29 @@ module Nondisposable
     DisposableDomain.disposable?(domain.downcase)
   end
 
+  # Does this address end in a TLD that actually exists?
+  #
+  # A different question from #disposable?, catching a different kind of bad
+  # address: `user@gmail.con` is not a throwaway, it is a typo that produces an
+  # account nobody can ever reach. Answers true for anything we cannot judge —
+  # no domain, no dot, an IP literal — so it is safe to call on any input; pair
+  # it with a format validation if you also care about shape.
+  def self.valid_tld?(email)
+    return true unless Tld.judgeable?(email)
+
+    tld = Tld.extract(email)
+    return false if tld.nil? # A domain with no TLD can't end in a real one
+
+    Tld.valid?(tld) && !Tld.blocked?(tld)
+  end
+
+  # "someone@gmial.com" => "someone@gmail.com", or nil when we have nothing
+  # useful to say. Never blocks anything by itself — hand it to a user and let
+  # them decide. See Nondisposable::Suggestion for how it decides.
+  def self.suggestion_for(email)
+    Suggestion.for(email)
+  end
+
   class Configuration
     ON_CHECK_FAILURE_MODES = [:allow, :reject].freeze
 
@@ -40,12 +66,78 @@ module Nondisposable
     attr_accessor :check_parent_domains
     attr_reader :on_check_failure
 
+    # ---- TLD validity (Nondisposable::Tld) ----------------------------------
+
+    # OFF by default, and it stays off: upgrading a gem must never silently
+    # start rejecting addresses that were fine yesterday. Turn it on to reject
+    # addresses whose TLD is not in the IANA root zone — `user@gmail.con` and
+    # friends, which are typos rather than throwaways but produce an account
+    # nobody can ever reach.
+    attr_accessor :check_tld
+
+    # Your escape hatch from a stale snapshot. A TLD delegated after this gem's
+    # release is unknown to the bundled list; naming it here accepts it
+    # immediately, with no release to wait for. Dots optional: "app" == ".app".
+    attr_accessor :additional_tlds
+
+    # TLDs to refuse even though they are perfectly real. The usual reason is
+    # abuse economics rather than validity — the historically free Freenom set
+    # (%w[tk ml ga cf gq]) is the classic example.
+    attr_accessor :blocked_tlds
+
+    # Allowlist mode: when set, ONLY these TLDs are accepted and every other one
+    # is refused. nil (the default) means "any TLD in the root zone". ⚠️ This is
+    # a blunt instrument — `%w[es]` turns away every customer who happens to use
+    # a .com address. Reach for blocked_tlds first.
+    attr_accessor :allowed_tlds
+
+    # ---- Lookalike domains (Nondisposable::Suggestion) ----------------------
+
+    # Reject addresses one edit away from a well-known provider — `gmail.co`,
+    # `gmial.com`, `hotmial.com` — with a message naming the correction.
+    #
+    # OFF by default and worth leaving off unless you have thought about it: a
+    # suggestion is a guess about intent, and a wrong guess here stops a real
+    # person signing up with their real address. `Nondisposable.suggestion_for`
+    # is always available and blocks nothing, which is the gentler way to use
+    # this: show the hint, let the human decide.
+    attr_accessor :reject_lookalike_domains
+
+    # How many edits still count as "a typo". 1 (the default) is the distance at
+    # which acting on a guess is safe; at 2, genuinely different domains start
+    # colliding with each other. 0 disables suggestions entirely.
+    attr_accessor :lookalike_distance
+
+    # Providers to add to the bundled list — your own domain, a regional
+    # provider we missed. Adding one both makes it a suggestion candidate and,
+    # more importantly, stops its users being told they made a typo.
+    attr_accessor :additional_email_providers
+
+    # ---- Error messages -----------------------------------------------------
+
+    attr_accessor :invalid_tld_error_message, :blocked_tld_error_message
+    # %{suggestion} is replaced with the full corrected address.
+    attr_accessor :lookalike_error_message
+
     def initialize
       @error_message = "provider is not allowed"
       @additional_domains = []
       @excluded_domains = []
       @on_check_failure = :allow
       @check_parent_domains = true
+
+      @check_tld = false
+      @additional_tlds = []
+      @blocked_tlds = []
+      @allowed_tlds = nil
+
+      @reject_lookalike_domains = false
+      @lookalike_distance = 1
+      @additional_email_providers = []
+
+      @invalid_tld_error_message = "doesn't look like a real email address"
+      @blocked_tld_error_message = "domain ending is not allowed"
+      @lookalike_error_message = "looks like a typo. Did you mean %{suggestion}?"
     end
 
     # What the validator does when the disposable check itself raises

data/lib/tasks/nondisposable.rake

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+namespace :nondisposable do
+  namespace :tlds do
+    desc "Refresh the vendored IANA TLD snapshot (maintenance task — run in a gem checkout before a release)"
+    task :update do
+      # Deliberately NOT `require "nondisposable"`: that loads the Engine, which
+      # needs Rails, which a bare `rake` in a gem checkout doesn't have. Nothing
+      # this task touches reads configuration — only `Tld.valid?`/`blocked?` do,
+      # and it calls neither.
+      require_relative "../nondisposable/tld"
+      require_relative "../nondisposable/tld_list_updater"
+
+      before = begin
+        Nondisposable::Tld.all.size
+      rescue StandardError
+        0
+      end
+
+      count = Nondisposable::TldListUpdater.update
+
+      if count.nil?
+        abort "[nondisposable] TLD list unchanged. See the error above."
+      else
+        added = count - before
+        change =
+          if added.positive? then "+#{added}"
+          elsif added.negative? then added.to_s
+          else "no change"
+          end
+        puts "[nondisposable] TLD snapshot now holds #{count} entries (#{change})."
+        puts "[nondisposable] IANA version: #{Nondisposable::Tld.version}"
+        puts "[nondisposable] Commit data/iana_tlds.txt if it changed."
+      end
+    end
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: nondisposable
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-08-09 00:00:00.000000000 Z
+date: 2026-08-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -43,6 +43,8 @@ files:
 - app/models/nondisposable/disposable_domain.rb
 - context7.json
 - data/disposable_email_blocklist.conf
+- data/email_providers.txt
+- data/iana_tlds.txt
 - gemfiles/rails_7.2.gemfile
 - gemfiles/rails_8.0.gemfile
 - gemfiles/rails_8.1.gemfile
@@ -54,7 +56,11 @@ files:
 - lib/nondisposable/domain_list_updater.rb
 - lib/nondisposable/email_validator.rb
 - lib/nondisposable/engine.rb
+- lib/nondisposable/suggestion.rb
+- lib/nondisposable/tld.rb
+- lib/nondisposable/tld_list_updater.rb
 - lib/nondisposable/version.rb
+- lib/tasks/nondisposable.rake
 - sig/nondisposable.rbs
 homepage: https://github.com/rameerez/nondisposable
 licenses: