imap.rb 0.4.9

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b062efdc696b59573e564f135485c3e987a8a8078b36e87783537cbcd040712a
+  data.tar.gz: 150f927c8023ed6cbbb1b58fa5b863620ba2043ec71058c52f36a75c817e9e0a
+SHA512:
+  metadata.gz: c979d4b09d86154e500454440396443d9db9ee8134603ea5d432ed093e46bc3a54fa33aaa24667302dc540566e8863c6d50c22c112c87ee91a1b224c7a4d567c
+  data.tar.gz: 4e91af7317d63811a9ec9dff17ff14130926bf101d4631e6fbfa5069501c12e90b1af0fa28efa315a6a1dc52b823b012e89f14e6d7dbdec3b8b7fe1fa44e3bff

data/CHANGELOG

@@ -0,0 +1,93 @@
+# imap/CHANGELOG
+
+## 20260917
+
+0.4.9: + imap.rb.gemspec, so that the gem resolves under both names.
+
+1. + imap.rb.gemspec: the same code published as imap.rb, which is how gems are named here: 21 carry the suffix and imap is one of the few which do not. rubygems has no notion of an alias, so the two are separate gems which must be kept at the same version by hand.
+2. It differs from imap.gemspec in the three lines measurand and namo differ in, the heading comment naming the file, the name, and the gemspec each lists among its own files. Neither ships the other.
+3. imap.rb is unregistered, so this is its first version. bitget, eodhd, measurand and webdav each had their second name join at whatever the first stood at rather than backfilling, and each did it as a patch of its own carrying nothing else.
+4. gem-publish builds and pushes each in turn, gem build and gem push taking one file apiece and gem build *.gemspec building only whichever the shell lists first.
+5. ~ Gemfile: gemspec name: 'imap', bundler refusing to choose between two gemspecs and stopping with "There are multiple gemspecs at ...". Every pair here which uses gemspec names one: webdav, measurand and eodhd each name the elder of their two, and namo, which carried both from its first release, names the bare one. imap is the elder here.
+6. ~ Imap::VERSION: /0.4.8/0.4.9/
+
+
+0.4.8: Rewrite the CHANGELOG in the standard form.
+
+1. ~ CHANGELOG: ## before each date rather than ## [version] - date, the version and its summary beneath, a blank line between that and the first item, and the items numbered rather than dashed. No item is reworded, dropped or reordered.
+2. ~ CHANGELOG: the dates in basic form, 20260910 for 2026-09-10, as every other gem here writes them.
+3. ~ CHANGELOG: + the title, # imap/CHANGELOG, as coinmarketcap.rb and release-audit have it.
+4. ~ CHANGELOG: the five releases of 20260917 under one date heading, which is how the form carries more than one in a day.
+5. 9 of the 12 gems here were already in this form; imap and gate.rb were not, which leaves gate.rb.
+6. ~ Imap::VERSION: /0.4.7/0.4.8/
+
+0.4.7: ~ Imap::Search: the chaining interface, which the header has documented and which has never run
+
+1. ~ Imap::Search: the generated methods named in lower case, so that from() answers where FROM() did. All 32 were upper case, being defined straight off the key constants, and none was reachable as the header wrote it.
+2. ~ Imap::Search: the generated methods return self, having returned the criteria hash, so that they chain.
+3. + Imap::Search#not: applies to what follows immediately and to nothing after it. + Negated, which carries a general key's value through the hash; a boolean needs none, false already reading as NOT.
+4. ~ Imap::Search#general_to_imap_search_key: ['NOT', key, value] where the value is Negated.
+5. ~ Imap::Search: the Usage header takes an imap_client, without which all() has nothing to search.
+6. + tests: the lower case names, that they chain, both negations, and that not applies once only.
+7. ~ Imap::VERSION: /0.4.6/0.4.7/
+
+0.4.6: ~ Imap::Message#body: BODY.PEEK[TEXT]; ~ Imap::Search#to_imap_search_keys: raise upon a key which is neither
+
+1. ~ Imap::Message#body: BODY.PEEK[TEXT] for BODY[TEXT]. Reading a body set \Seen, so anything which looked at one marked it read; PEEK is the whole of the difference and the response still answers to BODY[TEXT].
+2. ~ Imap::Search#to_imap_search_keys: + UnknownSearchKey where the case matched neither operator. An unrecognised key was dropped and the search ran wider than it was asked for, saying nothing.
+3. ~ Imap::Message#to: [] where the envelope carries no to, which raised NoMethodError upon nil.
+4. ~ test/test_helper.rb: MockIMAP answers BODY.PEEK[TEXT] with BODY[TEXT] as a server does, records the attrs fetched, and gives message 99 an envelope with no to.
+5. + a test apiece: that #body peeks, that #to is empty where there is no to, and that an unknown key raises.
+6. ~ Imap::VERSION: /0.4.5/0.4.6/
+
+0.4.5: + Gemfile; ~ imap.gemspec: dependencies=, - spec.date, + metadata
+
+1. + Gemfile: source and gemspec, as switches, eodhd and moby have it, so that the dependencies are declared once in the gemspec rather than restated here to drift. bitget and coinmarketcap restate theirs and are the minority. This was the only gem here with no Gemfile at all.
+2. ~ imap.gemspec: + 'Gemfile' to spec.files, which every other gem here ships.
+3. ~ imap.gemspec: dependencies= and development_dependencies= through the Gem::Specification extension, as switches, eodhd and moby have it and as bitget, coinmarketcap and this did not. The constraints survive: the splat takes a bare string or a [name, constraint] pair alike.
+4. ~ imap.gemspec: - spec.date = '2025-12-20', nine months and two versions stale, and the last one left in the estate. RubyGems answers 1980-01-02 in its place, the reproducible-build epoch, which is what coinmarketcap has carried since dropping its own at 0.6.0.
+5. ~ imap.gemspec: + metadata, the four uris switches and moby declare, so that the RubyGems page links to the issues, the changelog, the source and the README. master here where moby says main, each by the branch it is on.
+6. ~ Imap::VERSION: /0.4.4/0.4.5/
+
+0.4.4: + Rakefile, - test/test_all.rb
+
+1. + Rakefile: Rake::TestTask over FileList['test/**/*_test.rb'], with libs for lib and test, and warning = true. The minimal form nine of the gems here use rather than the fuller one five use: the :spec alias and the :version task belong to the minority, and a :version task reading VERSION.rb would not have caught 0.4.1, where require 'imap' left Imap::VERSION undefined while VERSION.rb sat there defining it. rake has been a development dependency since 0.4.0 with nothing here to run.
+2. - test/test_all.rb: a second entry point which the Rakefile's FileList makes redundant, and which had drifted from the files on disk in two ways: it never loaded test/Imap/VERSION_test.rb, added in 0.4.2, so it ran 42 tests where there are 44; and it required './Imap_test' for a file named imap_test.rb, which resolved only because the filesystem is case insensitive and would not have on Linux. A glob cannot drift. 14 of the 16 gems here with a Rakefile carry no such file; switches keeps spec/all.rb because its Rakefile targets it, and bitget carries the same redundancy this removes.
+3. ~ test/Imap/Message_test.rb: must_match(/Mock body/) for must_match /Mock body/, the ambiguous / which warning = true reports and which is the only warning the suite raises.
+4. ~ imap.gemspec: + 'Rakefile' to spec.files, as eodhd, switches and moby have.
+5. ~ Imap::VERSION: /0.4.3/0.4.4/
+
+0.4.3: ~ test/test_helper.rb: + require 'minitest/mock', which minitest 6 no longer brings
+
+1. ~ test/test_helper.rb: + `require 'minitest/mock'`. 35 of the 42 tests call stub and not one of them could: the suite answered "42 runs, 7 assertions, 0 failures, 35 errors". minitest 5's autorun required minitest/mock and shipped it, so the suite ran until minitest 6 dropped both the require and the file; the same thing coinmarketcap 0.6.1 found.
+2. ~ imap.gemspec: + minitest-mock as a development dependency, which minitest ~> 5.0 carried and minitest 6 does not.
+3. ~ Imap::VERSION: /0.4.2/0.4.3/
+
+
+## 20260910
+
+0.4.2: ~ lib/imap.rb: + require_relative './Imap/VERSION'; + test/Imap/VERSION_test.rb
+
+1. ~ lib/imap.rb: + `require_relative './Imap/VERSION'`, last among the requires. The file had been present and unreached, so `require 'imap'` left Imap::VERSION undefined and the gemspec was the only thing loading it.
+2. + test/Imap/VERSION_test.rb: that Imap::VERSION is a string and that it is three numbers separated by dots. Modelled on moby's, less the example comparing against the changelog, which was unreachable here while the file was misspelt.
+3. The test loads the library rather than VERSION.rb, which is the whole of its value: run against v0.4.1 it fails with "uninitialized constant Imap::VERSION". Nine libraries were in that state and not one of them carried this test.
+4. ~ Imap::VERSION: /0.4.1/0.4.2/
+
+
+## 20260822
+
+0.4.1: + LICENSE; ~ imap.gemspec: + CHANGELOG
+
+1. + LICENSE: the MIT text, copyright 2025-2026 thoran. The gemspec had declared MIT while the repository carried no licence text at all.
+2. ~ imap.gemspec: + 'LICENSE' and 'CHANGELOG' to spec.files, neither of which the gem had been shipping.
+3. ~ Imap::VERSION: /0.4.0/0.4.1/
+
+
+## 20251220
+
+0.4.0: Cleanup for publishing.
+
+1. /ImapClient/Imap/
+2. + imap.gemspec
+3. + tests
+4. + Imap::Message#to.

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec name: 'imap'

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 thoran
+
+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,77 @@
+# imap
+
+A Ruby wrapper around Net::IMAP with an elegant DSL for searching, reading, and managing email.
+
+## Features
+
+- Clean, hash-based search interface
+- Intuitive message accessors
+- No Rails dependency - works anywhere
+- Zero external dependencies beyond net-imap
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'imap'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install imap
+```
+
+## Usage
+```ruby
+require 'imap'
+
+# Connect and authenticate
+imap_client = Imap.setup(
+  server: 'imap.thoran.com',
+  username: 'code@thoran.com',
+  password: 'bigsecret',
+  mailbox: 'INBOX' # optional/default
+)
+
+messages = imap_client.search(
+  from: 'noreply@example.com',
+  subject: 'Payday Loans',
+  since: '18-DEC-2025',
+  seen: false
+)
+
+# Access message details
+messages.each do |message|
+  puts message.subject
+  puts message.from
+  puts message.to
+  puts message.body
+  puts message.urls # Extracted URLs from body
+end
+
+# Mark messages as read
+messages.first.mark_as_read
+
+# Clean up
+imap_client.bye
+```
+
+## Contributing
+
+1. Fork it (https://github.com/thoran/imap/fork)
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new pull request
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,12 @@
+# Rakefile
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.test_files = FileList['test/**/*_test.rb']
+  t.warning = true
+end
+
+task default: :test

data/imap.rb.gemspec

@@ -0,0 +1,58 @@
+# imap.rb.gemspec
+
+require_relative './lib/Imap/VERSION'
+
+class Gem::Specification
+  def dependencies=(gems)
+    gems.each{|gem| add_dependency(*gem)}
+  end
+
+  def development_dependencies=(gems)
+    gems.each{|gem| add_development_dependency(*gem)}
+  end
+end
+
+Gem::Specification.new do |spec|
+  spec.name = 'imap.rb'
+
+  spec.version = Imap::VERSION
+
+  spec.summary = "IMAP for Ruby made easy."
+  spec.description = "A Ruby wrapper around Net::IMAP with an elegant DSL for searching, reading, and managing email."
+
+  spec.author = 'thoran'
+  spec.email = 'code@thoran.com'
+  spec.homepage = 'https://github.com/thoran/imap'
+  spec.license = 'MIT'
+
+  spec.required_ruby_version = '>= 2.7'
+
+  spec.dependencies = [
+    ['net-imap', '~> 0.4']
+  ]
+
+  spec.development_dependencies = [
+    ['minitest', '~> 5.0'],
+    'minitest-mock',
+    ['rake', '~> 13.0']
+  ]
+
+  spec.files = [
+    'imap.rb.gemspec',
+    Dir['lib/**/*.rb'],
+    Dir['test/**/*.rb'],
+    'CHANGELOG',
+    'Gemfile',
+    'Rakefile',
+    'LICENSE',
+    'README.md',
+  ].flatten
+  spec.require_paths = ['lib']
+
+  spec.metadata = {
+    "bug_tracker_uri" => "https://github.com/thoran/imap/issues",
+    "changelog_uri" => "https://github.com/thoran/imap/blob/master/CHANGELOG",
+    "source_code_uri" => "https://github.com/thoran/imap",
+    "documentation_uri" => "https://github.com/thoran/imap/blob/master/README.md"
+  }
+end

data/lib/Imap/Message.rb

@@ -0,0 +1,67 @@
+# Imap/Message.rb
+# Imap::Message
+
+# Usage:
+# 1. Imap::Message.search(imap_client, {from: 'noreply@example.com'})
+# 2. Imap::Message.new(message_id, imap_client)
+# 3. Imap::Message.new(message_id, imap_client).body
+# 4. Imap::Message.new(message_id, imap_client).urls
+# 5. Imap::Message.new(message_id, imap_client).mark_as_read
+# 6. Imap::Message.new(message_id, imap_client).subject
+# 7. Imap::Message.new(message_id, imap_client).from
+# 8. Imap::Message.new(message_id, imap_client).to
+
+require_relative './Search'
+
+class Imap
+  class Message
+    class << self
+
+      def search(imap_client, **search_criteria)
+        message_ids = Imap::Search.new(imap_client, search_criteria).message_ids
+        message_ids.collect{|message_id| Imap::Message.new(message_id, imap_client)}
+      end
+      alias_method :find, :search
+
+    end # class << self
+
+    attr_accessor :imap_client
+    attr_accessor :message_id
+
+    def body
+      @body ||= fetch_data('BODY.PEEK[TEXT]').first.attr['BODY[TEXT]']
+    end
+
+    def subject
+      @subject ||= fetch_data('BODY[HEADER.FIELDS (SUBJECT)]').first.attr['BODY[HEADER.FIELDS (SUBJECT)]'].sub(/^Subject: /, '').strip
+    end
+
+    def from
+      @from ||= fetch_data('BODY[HEADER.FIELDS (FROM)]').first.attr['BODY[HEADER.FIELDS (FROM)]'].sub(/^From: /, '').strip
+    end
+
+    def to
+      @to ||= (fetch_data('ENVELOPE').first.attr['ENVELOPE'].to || []).map{|addr| addr.mailbox + '@' + addr.host}
+    end
+
+    def urls
+      body.scan(/https?:\/\/[\S]+/)
+    end
+
+    def mark_as_seen
+      imap_client.imap.store(@message_id, '+FLAGS', [:Seen])
+    end
+    alias_method :mark_as_read, :mark_as_seen
+
+    private
+
+    def initialize(message_id = nil, imap_client = nil)
+      @message_id = message_id
+      @imap_client = imap_client
+    end
+
+    def fetch_data(*attrs)
+      @fetch_data = imap_client.imap.fetch(message_id, [*attrs])
+    end
+  end
+end

data/lib/Imap/Search.rb

@@ -0,0 +1,166 @@
+# Imap/Search.rb
+# Imap::Search
+
+# Usage:
+# 1. Imap::Search.new(imap_client).not.subject('Payday Loans').answered.from('noreply@example.com').all
+# 2. Imap::Search.new(imap_client, {from: 'noreply@example.com', answered: true})
+
+# Notes:
+# 1. List of search keys taken from RFC-3501 (INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1), http://tools.ietf.org/html/rfc3501.
+
+class Imap
+  class Search
+
+    class UnknownSearchKey < ArgumentError; end
+
+    # A general key carries its value; negating one has to carry both, the hash
+    # having nowhere else to put it.  A boolean key needs none of this: false
+    # already reads as NOT.
+    Negated = Struct.new(:value)
+
+    ALL_SEARCH_KEYS = %w{
+      ALL
+      ANSWERED
+      BCC
+      BEFORE
+      BODY
+      CC
+      DELETED
+      DRAFT
+      FLAGGED
+      FROM
+      HEADER
+      KEYWORD
+      LARGER
+      NEW
+      NOT
+      OLD
+      ON
+      OR
+      RECENT
+      SEEN
+      SENTBEFORE
+      SENTON
+      SENTSINCE
+      SINCE
+      SMALLER
+      SUBJECT
+      TEXT
+      TO
+      UID
+      UNANSWERED
+      UNDELETED
+      UNDRAFT
+      UNFLAGGED
+      UNKEYWORD
+      UNSEEN
+    }
+
+    BOOLEAN_SEARCH_KEYS = %w{
+      ANSWERED UNANSWERED
+      DELETED UNDELETED
+      DRAFT UNDRAFT
+      FLAGGED UNFLAGGED
+      NEW
+      OLD
+      RECENT
+      SEEN UNSEEN
+    }
+
+    GENERAL_SEARCH_KEYS = %w{
+      BCC
+      BEFORE
+      BODY
+      CC
+      FROM
+      HEADER
+      KEYWORD UNKEYWORD
+      LARGER
+      ON
+      SENTBEFORE
+      SENTON
+      SENTSINCE
+      SINCE
+      SMALLER
+      SUBJECT
+      TEXT
+      TO
+      UID
+    }
+
+    BOOLEAN_SEARCH_KEYS.each do |boolean_search_key|
+      define_method boolean_search_key.downcase do |value = true|
+        criteria.merge!(boolean_search_key.to_sym => negating? ? !value : value)
+        self
+      end
+    end
+
+    GENERAL_SEARCH_KEYS.each do |general_search_key|
+      define_method general_search_key.downcase do |value|
+        criteria.merge!(general_search_key.to_sym => negating? ? Negated.new(value) : value)
+        self
+      end
+    end
+
+    # Applies to what follows immediately, and to nothing after that.
+    def not
+      @negate = true
+      self
+    end
+
+    attr_accessor :criteria
+    attr_accessor :imap_client
+
+    def general_operator?(search_key)
+      GENERAL_SEARCH_KEYS.include?(search_key)
+    end
+
+    def boolean_operator?(search_key)
+      BOOLEAN_SEARCH_KEYS.include?(search_key)
+    end
+
+    def to_imap_search_keys
+      criteria.inject([]) do |m, kv|
+        key, value = kv.first.to_s.upcase, kv.last
+        case
+        when general_operator?(key)
+          m << general_to_imap_search_key(key, value)
+        when boolean_operator?(key)
+          m << boolean_to_imap_search_key(key, value)
+        else
+          raise UnknownSearchKey, "no such search key: #{key}"
+        end
+      end.flatten
+    end
+
+    def general_to_imap_search_key(key, value)
+      value.is_a?(Negated) ? ['NOT', key, value.value] : [key, value]
+    end
+
+    def boolean_to_imap_search_key(key, value)
+      if value
+        [key]
+      else
+        ['NOT', key]
+      end
+    end
+
+    def negating?
+      negate = @negate
+      @negate = false
+      negate
+    end
+
+    def message_ids
+      imap_client.imap.search(to_imap_search_keys)
+    end
+    alias_method :all, :message_ids
+
+    private
+
+    def initialize(imap_client = nil, criteria = nil)
+      @criteria = criteria || {}
+      @imap_client = imap_client
+    end
+  end
+end

data/lib/Imap/VERSION.rb

@@ -0,0 +1,3 @@
+class Imap
+  VERSION = '0.4.9'
+end

data/lib/imap.rb

@@ -0,0 +1,83 @@
+# imap.rb
+# Imap
+
+require 'net/imap'
+require_relative './Imap/Message'
+require_relative './Imap/VERSION'
+
+class Imap
+  class << self
+
+    def setup(config)
+      raise ArgumentError, "Server must be specified" unless config[:server]
+      imap_client = Imap.new(**config)
+      if config[:username] && config[:password]
+        imap_client.login(username: config[:username], password: config[:password])
+      end
+      if config[:mailbox]
+        imap_client.mailbox = config[:mailbox]
+      end
+      imap_client
+    end
+
+  end # class << self
+
+  attr_accessor :server
+  attr_accessor :ssl
+  attr_accessor :username
+  attr_accessor :password
+  attr_reader :mailbox
+
+  def login(username: nil, password: nil)
+    username ||= @username
+    password ||= @password
+    begin
+      imap.login(username, password)
+      true
+    rescue Net::IMAP::NoResponseError, Net::IMAP::BadResponseError
+      false
+    end
+  end
+
+  def mailbox=(mailbox)
+    @mailbox = mailbox
+    imap.select(mailbox)
+  end
+
+  def search(criteria = {})
+    Imap::Message.search(self, **criteria)
+  end
+  alias_method :messages, :search
+  alias_method :find, :search
+
+  def bye
+    logout
+    disconnect
+  end
+
+  def logout
+    imap.logout
+  end
+
+  def disconnect
+    imap.disconnect
+  end
+
+  def imap
+    @imap ||= Net::IMAP.new(server, ssl: @ssl)
+  end
+
+  def ssl?
+    @ssl
+  end
+
+  private
+
+  def initialize(server:, ssl: true, username: nil, password: nil, mailbox: 'INBOX')
+    @server = server
+    @ssl = ssl
+    @username = username
+    @password = password
+    @mailbox = mailbox
+  end
+end

data/test/Imap/Message_test.rb

@@ -0,0 +1,121 @@
+# test/Imap/Message_test.rb
+
+require_relative '../test_helper'
+
+describe Imap::Message do
+  let(:client) do
+    mock_imap = MockIMAP.new('imap.example.com', ssl: true)
+    Net::IMAP.stub(:new, mock_imap) do
+      Imap.setup(
+        server: 'imap.example.com',
+        username: 'user@example.com',
+        password: 'secret'
+      )
+    end
+  end
+
+  let(:imap_message) do
+    Imap::Message.new(1, client)
+  end
+
+  describe '.search' do
+    it 'returns an array of messages' do
+      messages = Imap::Message.search(client, from: 'test@example.com')
+      _(messages).must_be_instance_of Array
+      _(messages.first).must_be_instance_of Imap::Message
+    end
+
+    it 'has find alias' do
+      _((Imap::Message.method(:find) == Imap::Message.method(:search))).must_equal true
+    end
+  end
+
+  describe '#body' do
+    it 'returns the message body' do
+      _(imap_message.body).must_match(/Mock body/)
+    end
+
+    it 'caches the result' do
+      first_call = imap_message.body
+      second_call = imap_message.body
+      _(first_call.object_id).must_equal second_call.object_id
+    end
+
+    it 'peeks, so that reading a body does not mark it seen' do
+      imap_message.body
+      _(client.imap.fetched_attrs).must_include 'BODY.PEEK[TEXT]'
+    end
+  end
+
+  describe '#subject' do
+    it 'returns the subject without prefix' do
+      _(imap_message.subject).must_match(/Mock Subject/)
+      _(imap_message.subject).wont_match(/^Subject:/)
+    end
+
+    it 'strips whitespace' do
+      _(imap_message.subject).must_equal(imap_message.subject.strip)
+    end
+  end
+
+  describe '#from' do
+    it 'returns the from address' do
+      _(imap_message.from).must_match(/sender@example.com/)
+    end
+
+    it 'removes From: prefix' do
+      _(imap_message.from).wont_match(/^From:/)
+    end
+  end
+
+  describe '#to' do
+    it 'returns an array of email addresses' do
+      addresses = imap_message.to
+      _(addresses).must_be_instance_of(Array)
+      _(addresses.first).must_match(/@/)
+    end
+
+    it 'formats addresses correctly' do
+      addresses = imap_message.to
+      _(addresses.first).must_equal('user@example.com')
+    end
+
+    it 'is empty where the envelope carries no to' do
+      _(Imap::Message.new(99, client).to).must_equal []
+    end
+  end
+
+  describe '#urls' do
+    it 'extracts http URLs from body' do
+      imap_message.stub(:body, 'Check out http://example.com and https://test.com') do
+        urls = imap_message.urls
+        _(urls).must_include('http://example.com')
+        _(urls).must_include('https://test.com')
+      end
+    end
+
+    it 'returns empty array when no URLs' do
+      imap_message.stub(:body, 'No URLs here') do
+        _(urls = imap_message.urls).must_be_empty
+      end
+    end
+  end
+
+  describe '#mark_as_seen' do
+    it 'marks the message as seen' do
+      _(imap_message.mark_as_seen).must_be_nil
+    end
+
+    it 'has mark_as_read alias' do
+      _((imap_message.method(:mark_as_read) == imap_message.method(:mark_as_seen))).must_equal true
+    end
+  end
+
+  describe '#initialize' do
+    it 'accepts message_id and imap_client' do
+      test_message = Imap::Message.new(42, client)
+      _(test_message.message_id).must_equal(42)
+      _(test_message.imap_client).must_equal(client)
+    end
+  end
+end

data/test/Imap/Search_test.rb

@@ -0,0 +1,120 @@
+# test/Imap/Search_test.rb
+
+require_relative '../test_helper'
+
+describe Imap::Search do
+  let(:client) do
+    mock_imap = MockIMAP.new('imap.example.com', ssl: true)
+    Net::IMAP.stub(:new, mock_imap) do
+      Imap.setup(
+        server: 'imap.example.com',
+        username: 'user@example.com',
+        password: 'secret'
+      )
+    end
+  end
+
+  let(:search) do
+    Imap::Search.new(client, {})
+  end
+
+  describe '#to_imap_search_keys' do
+    it 'converts general search keys' do
+      test_search = Imap::Search.new(client, from: 'test@example.com')
+      keys = test_search.to_imap_search_keys
+      _(keys).must_include 'FROM'
+      _(keys).must_include 'test@example.com'
+    end
+
+    it 'converts boolean search keys' do
+      test_search = Imap::Search.new(client, seen: false)
+      keys = test_search.to_imap_search_keys
+      _(keys).must_include 'NOT'
+      _(keys).must_include 'SEEN'
+    end
+
+    it 'raises upon a key which is neither' do
+      _{Imap::Search.new(client, bogus: 'x').to_imap_search_keys}.must_raise Imap::Search::UnknownSearchKey
+    end
+
+    it 'handles multiple criteria' do
+      test_search = Imap::Search.new(client, from: 'test@example.com', seen: true)
+      keys = test_search.to_imap_search_keys
+      _(keys.length).must_be :>, 2
+    end
+  end
+
+  describe 'the chaining interface' do
+    it 'names the keys in lower case' do
+      _(Imap::Search.new(client).from('x@y.com').criteria).must_equal({FROM: 'x@y.com'})
+    end
+
+    it 'returns itself, so that it chains' do
+      search = Imap::Search.new(client)
+      _(search.from('x@y.com')).must_be_same_as search
+    end
+
+    it 'negates a general key' do
+      _(Imap::Search.new(client).not.subject('Payday Loans').to_imap_search_keys).must_equal ['NOT', 'SUBJECT', 'Payday Loans']
+    end
+
+    it 'negates a boolean key' do
+      _(Imap::Search.new(client).not.seen.to_imap_search_keys).must_equal ['NOT', 'SEEN']
+    end
+
+    it 'negates what follows immediately and nothing after it' do
+      keys = Imap::Search.new(client).not.subject('Payday Loans').answered.from('noreply@example.com').to_imap_search_keys
+      _(keys).must_equal ['NOT', 'SUBJECT', 'Payday Loans', 'ANSWERED', 'FROM', 'noreply@example.com']
+    end
+  end
+
+  describe '#message_ids' do
+    it 'returns an array of message IDs' do
+      ids = search.message_ids
+      _(ids).must_be_instance_of Array
+    end
+
+    it 'has all alias' do
+      _((search.method(:all) == search.method(:message_ids))).must_equal true
+    end
+  end
+
+  describe '#boolean_operator?' do
+    it 'returns true for boolean operators' do
+      _(search.boolean_operator?('SEEN')).must_equal true
+      _(search.boolean_operator?('ANSWERED')).must_equal true
+    end
+
+    it 'returns false for general operators' do
+      _(search.boolean_operator?('FROM')).must_equal false
+    end
+  end
+
+  describe '#general_operator?' do
+    it 'returns true for general operators' do
+      _(search.general_operator?('FROM')).must_equal true
+      _(search.general_operator?('SUBJECT')).must_equal true
+    end
+
+    it 'returns false for boolean operators' do
+      _(search.general_operator?('SEEN')).must_equal false
+    end
+  end
+
+  describe '#initialize' do
+    it 'accepts imap_client parameter' do
+      test_search = Imap::Search.new(client)
+      _(test_search.imap_client).must_equal client
+    end
+
+    it 'accepts criteria parameter' do
+      test_search = Imap::Search.new(client, from: 'test@example.com')
+      _(test_search.criteria).must_equal({ from: 'test@example.com' })
+    end
+
+    it 'defaults criteria to empty hash' do
+      test_search = Imap::Search.new(client)
+      _(test_search.criteria).must_equal({})
+    end
+  end
+end

data/test/Imap/VERSION_test.rb

@@ -0,0 +1,15 @@
+# test/Imap/VERSION_test.rb
+
+require_relative '../test_helper'
+
+describe Imap do
+  describe "VERSION" do
+    it "is a string" do
+      _(Imap::VERSION).must_be_instance_of String
+    end
+
+    it "is three numbers separated by dots" do
+      _(Imap::VERSION).must_match(/\A\d+\.\d+\.\d+\z/)
+    end
+  end
+end

data/test/Imap_test.rb

@@ -0,0 +1,119 @@
+# test/imap_test.rb
+
+require_relative './test_helper'
+
+describe Imap do
+  let(:client) do
+    Net::IMAP.stub(:new, MockIMAP.new('imap.example.com', ssl: true)) do
+      Imap.setup(
+        server: 'imap.example.com',
+        username: 'user@example.com',
+        password: 'secret',
+        mailbox: 'INBOX'
+      )
+    end
+  end
+
+  describe ".setup" do
+    it 'creates a new client instance' do
+      _(client).must_be_instance_of(Imap)
+    end
+
+    it 'requires a server parameter' do
+      _(proc{Imap.setup({})}).must_raise(ArgumentError)
+    end
+
+    it 'sets the server' do
+      _(client.server).must_equal 'imap.example.com'
+    end
+
+    it 'defaults ssl to true' do
+      _(client.ssl?).must_equal true
+    end
+
+    it 'defaults mailbox to INBOX' do
+      _(client.mailbox).must_equal 'INBOX'
+    end
+  end
+
+  describe "#login" do
+    it 'returns true on successful login' do
+      Net::IMAP.stub(:new, MockIMAP.new('imap.example.com', ssl: true)) do
+        test_client = Imap.new(server: 'imap.example.com')
+        result = test_client.login(username: 'user', password: 'pass')
+        _(result).must_equal true
+      end
+    end
+
+    it 'returns false on failed login' do
+      mock = MockIMAP.new('imap.example.com', ssl: true)
+      def mock.login(username, password)
+        mock_response = OpenStruct.new(data: OpenStruct.new(text: 'Authentication failed'))
+        raise Net::IMAP::BadResponseError, mock_response
+      end
+
+      Net::IMAP.stub(:new, mock) do
+        test_client = Imap.new(server: 'imap.example.com')
+        result = test_client.login(username: 'user', password: 'wrong')
+        _(result).must_equal false
+      end
+    end
+  end
+
+  describe "#mailbox=" do
+    it 'sets the mailbox' do
+      Net::IMAP.stub(:new, MockIMAP.new('imap.example.com', ssl: true)) do
+        test_client = Imap.new(server: 'imap.example.com')
+        test_client.mailbox = 'Sent'
+        _(test_client.mailbox).must_equal 'Sent'
+      end
+    end
+  end
+
+  describe "#search" do
+    it 'returns an array of Message objects' do
+      Net::IMAP.stub(:new, MockIMAP.new('imap.example.com', ssl: true)) do
+        test_client = Imap.setup(
+          server: 'imap.example.com',
+          username: 'user',
+          password: 'pass'
+        )
+        messages = test_client.search(from: 'test@example.com')
+        _(messages).must_be_instance_of Array
+        _(messages.first).must_be_instance_of Imap::Message
+      end
+    end
+
+    it 'has messages and find aliases' do
+      _((client.method(:messages) == client.method(:search))).must_equal true
+      _((client.method(:find) == client.method(:search))).must_equal true
+    end
+  end
+
+  describe "#initialize" do
+    it 'accepts server parameter' do
+      test_client = Imap.new(server: 'mail.example.com')
+      _(test_client.server).must_equal 'mail.example.com'
+    end
+
+    it 'accepts ssl parameter' do
+      test_client = Imap.new(server: 'mail.example.com', ssl: false)
+      _(test_client.ssl?).must_equal false
+    end
+
+    it 'accepts username parameter' do
+      test_client = Imap.new(server: 'mail.example.com', username: 'test@example.com')
+      _(test_client.username).must_equal 'test@example.com'
+    end
+
+    it 'accepts password parameter' do
+      test_client = Imap.new(server: 'mail.example.com', password: 'secret')
+      _(test_client.password).must_equal 'secret'
+    end
+
+    it 'accepts mailbox parameter' do
+      test_client = Imap.new(server: 'mail.example.com', mailbox: 'Sent')
+      _(test_client.mailbox).must_equal 'Sent'
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,78 @@
+# test/test_helper.rb
+
+require 'minitest/autorun'
+require 'minitest/mock'
+require 'minitest/spec'
+require 'ostruct'
+require_relative '../lib/imap'
+
+class MockIMAP
+  attr_reader :login_called
+  attr_reader :logout_called
+  attr_reader :search_called
+  attr_reader :search_criteria
+  attr_reader :select_called
+  attr_reader :selected_mailbox
+
+  def login(username, password)
+    @login_called = true
+    @username = username
+    @password = password
+  end
+
+  def select(mailbox)
+    @select_called = true
+    @selected_mailbox = mailbox
+  end
+
+  def search(criteria)
+    @search_called = true
+    @search_criteria = criteria
+    [1, 2, 3]
+  end
+
+  attr_reader :fetched_attrs
+
+  def fetch(message_id, attrs)
+    @fetched_attrs = attrs
+    [OpenStruct.new(attr: mock_fetch_attrs(message_id, attrs))]
+  end
+
+  def store(message_id, flags, values); end
+
+  def logout
+    @logout_called = true
+  end
+
+  def disconnect; end
+
+  private
+
+  def initialize(server, ssl:)
+    @server = server
+    @ssl = ssl
+    @login_called = false
+    @select_called = false
+    @search_called = false
+    @logout_called = false
+  end
+
+  def mock_fetch_attrs(message_id, attrs)
+    result = {}
+    attrs.each do |attr|
+      case attr
+      when 'BODY[TEXT]', 'BODY.PEEK[TEXT]'
+        result['BODY[TEXT]'] = "Mock body for message #{message_id}"
+      when 'BODY[HEADER.FIELDS (SUBJECT)]'
+        result['BODY[HEADER.FIELDS (SUBJECT)]'] = "Subject: Mock Subject #{message_id}\r\n"
+      when 'BODY[HEADER.FIELDS (FROM)]'
+        result['BODY[HEADER.FIELDS (FROM)]'] = "From: sender@example.com\r\n"
+      when 'ENVELOPE'
+        result['ENVELOPE'] = OpenStruct.new(
+          to: message_id == 99 ? nil : [OpenStruct.new(mailbox: 'user', host: 'example.com')]
+        )
+      end
+    end
+    result
+  end
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: imap.rb
+version: !ruby/object:Gem::Version
+  version: 0.4.9
+platform: ruby
+authors:
+- thoran
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: net-imap
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: minitest-mock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: A Ruby wrapper around Net::IMAP with an elegant DSL for searching, reading,
+  and managing email.
+email: code@thoran.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- imap.rb.gemspec
+- lib/Imap/Message.rb
+- lib/Imap/Search.rb
+- lib/Imap/VERSION.rb
+- lib/imap.rb
+- test/Imap/Message_test.rb
+- test/Imap/Search_test.rb
+- test/Imap/VERSION_test.rb
+- test/Imap_test.rb
+- test/test_helper.rb
+homepage: https://github.com/thoran/imap
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/thoran/imap/issues
+  changelog_uri: https://github.com/thoran/imap/blob/master/CHANGELOG
+  source_code_uri: https://github.com/thoran/imap
+  documentation_uri: https://github.com/thoran/imap/blob/master/README.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: IMAP for Ruby made easy.
+test_files: []