pec_ruby 0.2.2 → 0.2.3

data/README.md

@@ -9,6 +9,9 @@ A comprehensive Ruby gem for decoding and managing Italian PEC (Posta Elettronic
 - **Nested PEC Support**: **NEW in v0.2.1** - Detects and processes forwarded PEC messages (nested postacert.eml files)
 - **Attachment Management**: Download and manage attachments easily
 - **Performance Optimized**: **NEW in v0.2.1** - Memoization for faster repeated access to attachments
+- **Ruby Way Behavior**: **NEW in v0.2.3** - Intuitive method behavior where `subject/from/to/date` always return the most relevant content
+- **Smart Body Access**: **NEW in v0.2.3** - Universal body access methods work with both received and sent messages
+- **Folder Management**: **NEW in v0.2.3** - Easy navigation and selection of PEC folders (INBOX, sent, drafts, etc.)
 - **CLI Included**: Command-line interface for exploring PEC messages
 - **Programmatic API**: Methods for integrating PEC functionality into your Ruby applications
 - **Comprehensive Testing**: Full test suite with both unit and integration tests
@@ -42,6 +45,7 @@ Or in your Gemfile:
 ```ruby
 gem 'pec_ruby'
 gem 'tty-prompt', '~> 0.23'
+gem 'tty-screen', '~> 0.8'
 gem 'awesome_print', '~> 1.9'
 ```
 
@@ -55,14 +59,53 @@ pec_ruby
 
 **Note**: If you installed only the library without CLI dependencies, the `pec_ruby` executable will inform you how to install them.
 
+**CLI Dependencies:**
+- `tty-prompt` (~> 0.23) - Interactive menus and prompts
+- `tty-screen` (~> 0.8) - Screen management and layout
+- `awesome_print` (~> 1.9) - Enhanced object printing
+
 The CLI allows you to:
 - Connect to your PEC server
-- Explore received messages
+- **NEW in v0.2.3**: Select and switch between different folders (INBOX, Sent, etc.)
+- Explore received messages with Ruby Way behavior (most relevant content displayed first)
 - View decoded original message contents
 - Download attachments
 - **NEW in v0.2.1**: Detect and process forwarded PEC messages (nested postacert.eml files)
 - **NEW in v0.2.1**: Enhanced performance with memoization for large attachments
 
+### CLI Workflow (v0.2.3)
+
+The CLI now features a **professional, full-screen interface** with enhanced performance and user experience:
+
+**🚀 Performance Improvements:**
+- **Optimized IMAP fetching**: Messages load in ~0.2s instead of several seconds
+- **Smart envelope caching**: List view uses only envelope data (no postacert fetching)
+- **Batch processing**: Efficient handling of large mailboxes
+- **On-demand loading**: Full message details fetched only when selected
+
+**🎨 Enhanced Interface:**
+- **Fixed header**: Banner and status always visible
+- **Clean screen management**: No scrolling, professional layout
+- **Interactive message viewer**: Menu-driven navigation with options
+- **Progress indicators**: Real-time feedback for all operations
+- **Folder management**: Easy switching between INBOX, Sent, Trash, etc.
+
+**📋 Complete Workflow:**
+1. **Connect** to your PEC server with credential validation
+2. **Select folder** from available options (INBOX, Sent, drafts, etc.)
+3. **Browse messages** with fast envelope-based listing
+4. **Message details** with interactive menu:
+   - View complete message body
+   - Download attachments with progress tracking
+   - Navigate between Ruby Way and PEC envelope data
+5. **Attachment management** with visual progress and batch download
+
+**Main Menu Options:**
+- **Connect to PEC server**: Secure login with connection status
+- **Select folder**: Visual folder picker with current selection indicator
+- **List and analyze messages**: Fast message browsing with timing information
+- **Disconnect**: Clean logout with confirmation
+
 ## Programmatic Usage
 
 ### Basic Connection
@@ -87,7 +130,7 @@ client.connect
 messages = client.messages(limit: 10)
 
 # Only PEC messages (with postacert.eml)
-pec_messages = client.pec_messages(limit: 10)
+messages = client.messages(limit: 10)
 
 # Specific message by UID
 message = client.message(12345)
@@ -96,7 +139,7 @@ message = client.message(12345)
 ### Working with Messages
 
 ```ruby
-message = client.pec_messages.first
+message = client.messages.first
 
 # PEC container information
 puts message.subject        # PEC message subject
@@ -190,6 +233,33 @@ client.connected?
 # Returns: Boolean
 ```
 
+##### `#available_folders` (NEW in v0.2.3)
+Lists all available folders in the mailbox.
+
+```ruby
+folders = client.available_folders
+# Returns: Array<String>
+# Example: ["INBOX", "INBOX.inviata", "INBOX.bozze", "INBOX.cestino"]
+```
+
+##### `#select_folder(folder)` (NEW in v0.2.3)
+Selects a specific folder for operations.
+
+```ruby
+client.select_folder('INBOX.inviata')
+# Returns: Net::IMAP response
+# Raises: PecRuby::FolderError if folder doesn't exist
+```
+
+##### `#select_inbox` (NEW in v0.2.3)
+Convenience method to select the INBOX folder.
+
+```ruby
+client.select_inbox
+# Returns: Net::IMAP response
+# Raises: PecRuby::FolderError if INBOX doesn't exist
+```
+
 ##### `#messages(limit: nil, reverse: true)`
 Retrieves messages from the server.
 
@@ -202,13 +272,6 @@ messages = client.messages(limit: 10, reverse: true)
 - `limit` (Integer, optional): Maximum number of messages to retrieve
 - `reverse` (Boolean): Return newest messages first (default: true)
 
-##### `#pec_messages(limit: nil, reverse: true)`
-Retrieves only messages containing postacert.eml.
-
-```ruby
-pec_messages = client.pec_messages(limit: 5)
-# Returns: Array<PecRuby::Message>
-```
 
 ##### `#message(uid)`
 Retrieves a specific message by UID.
@@ -224,39 +287,65 @@ Represents a PEC message with access to both container and original message data
 
 #### Instance Methods
 
-##### Basic PEC Container Information
+##### Ruby Way Behavior - Most Relevant Content (NEW in v0.2.3)
 
 ```ruby
-# PEC envelope information
+# These methods return the most relevant content:
+# - postacert.eml content if available (received messages)
+# - direct message content if no postacert.eml (sent messages)
 message.uid            # Integer: Message UID
-message.subject        # String: PEC subject (cleaned)
-message.from           # String: PEC sender
-message.to             # Array<String>: PEC recipients
-message.date           # Time: PEC message date
+message.subject        # String: Most relevant subject
+message.from           # String: Most relevant sender
+message.to             # Array<String>: Most relevant recipients
+message.date           # Time: Most relevant message date
+message.has_postacert? # Boolean: Check if postacert.eml is available
 ```
 
-##### Original Message Access
+##### PEC Container Access
 
 ```ruby
-# Check if postacert.eml is available
-message.has_postacert?    # Boolean
+# These methods always return the outer PEC container information
+message.original_subject  # String: PEC envelope subject (cleaned)
+message.original_from     # String: PEC envelope sender
+message.original_to       # Array<String>: PEC envelope recipients
+message.original_date     # Time: PEC envelope date
+```
 
-# Original message information
-message.original_subject  # String: Original subject
-message.original_from     # String: Original sender
-message.original_to       # Array<String>: Original recipients
-message.original_date     # Time: Original message date
-message.original_body     # Hash: Original message body with format info
-message.original_body_text  # String: Plain text body only
-message.original_body_html  # String: HTML body only
+##### Postacert.eml Access
+
+```ruby
+# Direct access to postacert.eml content (nil if not available)
+message.postacert_body       # Hash: Postacert message body with format info
+message.postacert_body_text  # String: Plain text body only
+message.postacert_body_html  # String: HTML body only
+
+# Legacy aliases for backward compatibility
+message.original_body        # Hash: Alias for postacert_body
+message.original_body_text   # String: Alias for postacert_body_text
+message.original_body_html   # String: Alias for postacert_body_html
 ```
 
-##### Original Message Body
+##### Smart Message Body Access (NEW in v0.2.3)
+
+```ruby
+# Smart body access - works with both received and sent messages
+message.raw_body          # Hash: Body with format info (postacert.eml if available, otherwise direct message)
+message.raw_body_text     # String: Plain text body (postacert.eml if available, otherwise direct message)
+message.raw_body_html     # String: HTML body (postacert.eml if available, otherwise direct message)
+```
+
+**Behavior:**
+- For received messages (with postacert.eml): Returns content from postacert.eml (same as `original_*` methods)
+- For sent messages (without postacert.eml): Returns content from the message itself
+- **Recommended**: Use `raw_body_*` methods for universal compatibility
+
+##### Message Body Handling
 
-The `original_body` method returns a hash with format information, allowing you to handle different content types appropriately:
+Both `original_body` and `raw_body` methods return a hash with format information, allowing you to handle different content types appropriately:
 
 ```ruby
-body_info = message.original_body
+# Use raw_body for universal compatibility (recommended)
+body_info = message.raw_body
 if body_info
   puts "Content type: #{body_info[:content_type]}"
   puts "Charset: #{body_info[:charset]}"
@@ -274,16 +363,24 @@ if body_info
 end
 
 # Or use convenience methods for specific formats
-text_only = message.original_body_text  # Returns nil if no text/plain part
-html_only = message.original_body_html  # Returns nil if no text/html part
+text_only = message.raw_body_text  # Works for both received and sent messages
+html_only = message.raw_body_html  # Works for both received and sent messages
+
+# Use original_* methods only when you specifically need postacert.eml content
+original_text = message.original_body_text  # Returns nil if no postacert.eml
+original_html = message.original_body_html  # Returns nil if no postacert.eml
 ```
 
 ##### Attachments
 
 ```ruby
-# Get original message attachments
-message.original_attachments         # Array<PecRuby::Attachment> - All attachments
-message.original_regular_attachments # Array<PecRuby::Attachment> - Non-postacert attachments only
+# Smart attachment access - returns most relevant attachments
+message.attachments                  # Array<PecRuby::Attachment> - Smart attachment access
+message.regular_attachments         # Array<PecRuby::Attachment> - Non-postacert attachments only
+
+# Direct postacert.eml attachment access
+message.postacert_attachments       # Array<PecRuby::Attachment> - All postacert attachments
+message.postacert_regular_attachments # Array<PecRuby::Attachment> - Non-postacert attachments only
 message.nested_postacerts           # Array<PecRuby::Attachment> - Nested postacert.eml files only
 
 # Check for nested postacerts (forwarded PECs)
@@ -292,6 +389,10 @@ message.nested_postacert_messages   # Array<PecRuby::NestedPostacertMessage>
 
 # Get all postacert messages in a flattened structure
 message.all_postacert_messages      # Array<Hash> - Hierarchical view of all messages
+
+# Legacy aliases for backward compatibility
+message.original_attachments        # Array<PecRuby::Attachment> - Alias for postacert_attachments
+message.original_regular_attachments # Array<PecRuby::Attachment> - Alias for postacert_regular_attachments
 ```
 
 ##### Summary Information
@@ -374,17 +475,19 @@ begin
   client.connect
 
   # Get last 5 PEC messages
-  pec_messages = client.pec_messages(limit: 5)
+  messages = client.messages(limit: 5)
   
-  pec_messages.each do |message|
-    puts "Subject: #{message.original_subject}"
-    puts "From: #{message.original_from}"
-    puts "Total attachments: #{message.original_attachments.size}"
-    puts "Regular attachments: #{message.original_regular_attachments.size}"
+  messages.each do |message|
+    # Ruby Way - these methods automatically return the most relevant content
+    puts "Subject: #{message.subject}"         # Postacert.eml subject if available, otherwise PEC envelope
+    puts "From: #{message.from}"               # Postacert.eml sender if available, otherwise PEC envelope
+    puts "Date: #{message.date}"               # Postacert.eml date if available, otherwise PEC envelope
+    puts "Total attachments: #{message.attachments.size}"
+    puts "Regular attachments: #{message.regular_attachments.size}"
     puts "Nested PECs: #{message.nested_postacerts.size}"
     
-    # Handle message body based on format
-    body_info = message.original_body
+    # Handle message body based on format - use raw_body for universal compatibility
+    body_info = message.raw_body
     if body_info
       puts "Body format: #{body_info[:content_type]}"
       case body_info[:content_type]
@@ -399,7 +502,7 @@ begin
     end
     
     # Download regular attachments
-    message.original_regular_attachments.each do |attachment|
+    message.regular_attachments.each do |attachment|
       attachment.save_to_dir('./downloads')
       puts "Downloaded: #{attachment.filename}"
     end
@@ -437,13 +540,76 @@ ensure
 end
 ```
 
+### Ruby Way Behavior Change (v0.2.3)
+
+**Important**: In v0.2.3, we've changed the behavior of core methods to be more intuitive and "Ruby Way":
+
+```ruby
+# OLD behavior (v0.2.2 and earlier)
+message.subject        # → Always PEC envelope subject
+message.original_subject # → Postacert.eml subject (if available)
+
+# NEW behavior (v0.2.3 and later) - Ruby Way
+message.subject        # → Postacert.eml subject if available, otherwise PEC envelope
+message.original_subject # → Always PEC envelope subject
+```
+
+**Migration**: Most code will continue to work, but if you specifically need PEC envelope data, use `original_*` methods. For postacert.eml data, use `postacert_*` methods or the legacy `original_*` aliases.
+
+### Working with Different Folders (NEW in v0.2.3)
+
+The gem now supports easy folder navigation:
+
+```ruby
+# List all available folders
+folders = client.available_folders
+puts "Available folders: #{folders.join(', ')}"
+# Output: Available folders: INBOX, INBOX.inviata, INBOX.bozze, INBOX.cestino
+
+# Select a specific folder
+client.select_folder('INBOX.inviata')
+# or use the convenience method for INBOX
+client.select_inbox
+
+# Get messages from the selected folder
+messages = client.messages(limit: 10)
+```
+
+### Working with Sent Messages
+
+The `raw_body_*` methods work seamlessly with sent messages (which don't have postacert.eml):
+
+```ruby
+# Get sent messages using the new folder methods
+client.select_folder('INBOX.inviata')
+sent_messages = client.messages(limit: 5)
+
+sent_messages.each do |message|
+  puts "Subject: #{message.subject}"
+  puts "From: #{message.from}"
+  puts "Date: #{message.date}"
+  puts "Has postacert: #{message.has_postacert?}"  # Will be false for sent messages
+  
+  # Use raw_body methods for universal compatibility
+  body_text = message.raw_body_text
+  if body_text
+    puts "Body preview: #{body_text[0..100]}..."
+  end
+  
+  # original_* methods will return nil for sent messages
+  puts "Original body: #{message.original_body_text.inspect}"  # => nil
+  
+  puts "─" * 40
+end
+```
+
 ### Nested PEC Detection Example (NEW in v0.2.1)
 
 Handle forwarded PEC messages that contain other PEC messages as attachments:
 
 ```ruby
 # Find a message with forwarded PECs
-message = client.pec_messages.find { |msg| msg.has_nested_postacerts? }
+message = client.messages.find { |msg| msg.has_nested_postacerts? }
 
 if message
   puts "Found message with #{message.nested_postacerts.size} forwarded PEC(s):"
@@ -482,6 +648,7 @@ PecRuby::ConnectionError       # Connection issues
 PecRuby::AuthenticationError   # Login failures
 PecRuby::MessageNotFoundError  # Message not found
 PecRuby::PostacertNotFoundError # postacert.eml not found
+PecRuby::FolderError           # Folder selection issues (NEW in v0.2.3)
 ```
 
 Example with error handling: