imap 0.4.5 → 0.4.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78ec20b3a5517359526f4c5e0437a05b1ab97be444c1e1c741992f1ea595376e
-  data.tar.gz: d5d2ac27eb982ff25264eaf947ee71981fba45cfc645b34dcce8148617a4c790
+  metadata.gz: 4b8f4ea427e7f3c30d6ce897ad13cdf4d22693b18170941d13c96f0e267bde83
+  data.tar.gz: 59a416b6e3687d94b3be00a9c2ce3c43090bd3ae09570b8cb0f9158f07d9a8a0
 SHA512:
-  metadata.gz: 6a470cbf282ff1c1b84e6283b8e6a882262e02379eb03a50a65657346624667f576c5f14fecc1471ac94be2d6fe83bdca7f0d57ba76d65f613330662527c8e50
-  data.tar.gz: 9754404cd62da6dfd26caa4e9c0ef3a7023704ff8f99da0864e57835a605b7c1dd04d4f992e35700184802ca1e6f075734ac89e3767234b1fd8cafb674f27315
+  metadata.gz: 16d311031d31ef2f8b50ebf349134429a3bd4a82174062ffbcf867369c23f039c444a099115ced05911f89093f5f30c3a0a4fe1014d45e1499beb6ecbf522fc4
+  data.tar.gz: '08dc54d7f1f9e867461b521f9383f9e6a56d3e747ee5ec697a53e7015c0f6df079fd2ec96cd8a677c3607bd824ec4e7cb4daefccde1acac09ad3265365457149'

data/CHANGELOG

@@ -1,5 +1,22 @@
 # CHANGELOG
 
+## [0.4.7] - 2026-09-17, ~ Imap::Search: the chaining interface, which the header has documented and which has never run
+- ~ 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.
+- ~ Imap::Search: the generated methods return self, having returned the criteria hash, so that they chain.
+- + 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.
+- ~ Imap::Search#general_to_imap_search_key: ['NOT', key, value] where the value is Negated.
+- ~ Imap::Search: the Usage header takes an imap_client, without which all() has nothing to search.
+- + tests: the lower case names, that they chain, both negations, and that not applies once only.
+- ~ Imap::VERSION: /0.4.6/0.4.7/
+
+## [0.4.6] - 2026-09-17, ~ Imap::Message#body: BODY.PEEK[TEXT]; ~ Imap::Search#to_imap_search_keys: raise upon a key which is neither
+- ~ 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].
+- ~ 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.
+- ~ Imap::Message#to: [] where the envelope carries no to, which raised NoMethodError upon nil.
+- ~ 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.
+- + a test apiece: that #body peeks, that #to is empty where there is no to, and that an unknown key raises.
+- ~ Imap::VERSION: /0.4.5/0.4.6/
+
 ## [0.4.5] - 2026-09-17, + Gemfile; ~ imap.gemspec: dependencies=, - spec.date, + metadata
 - + 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.
 - ~ imap.gemspec: + 'Gemfile' to spec.files, which every other gem here ships.

data/lib/Imap/Message.rb

@@ -29,7 +29,7 @@ class Imap
     attr_accessor :message_id
 
     def body
-      @body ||= fetch_data('BODY[TEXT]').first.attr['BODY[TEXT]']
+      @body ||= fetch_data('BODY.PEEK[TEXT]').first.attr['BODY[TEXT]']
     end
 
     def subject
@@ -41,7 +41,7 @@ class Imap
     end
 
     def to
-      @to ||= fetch_data('ENVELOPE').first.attr['ENVELOPE'].to.map{|addr| addr.mailbox + '@' + addr.host}
+      @to ||= (fetch_data('ENVELOPE').first.attr['ENVELOPE'].to || []).map{|addr| addr.mailbox + '@' + addr.host}
     end
 
     def urls

data/lib/Imap/Search.rb

@@ -2,8 +2,8 @@
 # Imap::Search
 
 # Usage:
-# 1. Imap::Search.new.not.subject('Payday Loans').answered.from('noreply@example.com').all
-# 2. Imap::Search.new({from: 'noreply@example.com', answered: true})
+# 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.
@@ -11,6 +11,13 @@
 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
@@ -82,17 +89,25 @@ class Imap
     }
 
     BOOLEAN_SEARCH_KEYS.each do |boolean_search_key|
-      define_method boolean_search_key do |value = true|
-        criteria.merge!(boolean_search_key.to_sym => value)
+      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 do |value|
-        criteria.merge!(general_search_key.to_sym => value)
+      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
 
@@ -112,12 +127,14 @@ class Imap
           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)
-      [key, value]
+      value.is_a?(Negated) ? ['NOT', key, value.value] : [key, value]
     end
 
     def boolean_to_imap_search_key(key, value)
@@ -128,6 +145,12 @@ class Imap
       end
     end
 
+    def negating?
+      negate = @negate
+      @negate = false
+      negate
+    end
+
     def message_ids
       imap_client.imap.search(to_imap_search_keys)
     end

data/lib/Imap/VERSION.rb

@@ -1,3 +1,3 @@
 class Imap
-  VERSION = '0.4.5'
+  VERSION = '0.4.7'
 end

data/test/Imap/Message_test.rb

@@ -40,6 +40,11 @@ describe Imap::Message do
       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
@@ -74,6 +79,10 @@ describe Imap::Message 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

data/test/Imap/Search_test.rb

@@ -33,6 +33,10 @@ describe Imap::Search do
       _(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
@@ -40,6 +44,30 @@ describe Imap::Search do
     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

data/test/test_helper.rb

@@ -31,7 +31,10 @@ class MockIMAP
     [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
 
@@ -58,7 +61,7 @@ class MockIMAP
     result = {}
     attrs.each do |attr|
       case attr
-      when 'BODY[TEXT]'
+      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"
@@ -66,7 +69,7 @@ class MockIMAP
         result['BODY[HEADER.FIELDS (FROM)]'] = "From: sender@example.com\r\n"
       when 'ENVELOPE'
         result['ENVELOPE'] = OpenStruct.new(
-          to: [OpenStruct.new(mailbox: 'user', host: 'example.com')]
+          to: message_id == 99 ? nil : [OpenStruct.new(mailbox: 'user', host: 'example.com')]
         )
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: imap
 version: !ruby/object:Gem::Version
-  version: 0.4.5
+  version: 0.4.7
 platform: ruby
 authors:
 - thoran
@@ -85,7 +85,7 @@ files:
 - test/Imap/Message_test.rb
 - test/Imap/Search_test.rb
 - test/Imap/VERSION_test.rb
-- test/imap_test.rb
+- test/Imap_test.rb
 - test/test_helper.rb
 homepage: https://github.com/thoran/imap
 licenses: