feat: v5.0.0! bug fixes and lib update

CHANGELOG.md

@@ -1,3 +1,9 @@
+## 5.0.0
+* minor interface changes.  Some are now const / final objects.
+* added a lot of tests
+* names of addresses may contain unicode characters now  
+  still no punycode support!
+
 ## 4.0.0
 * null safety and cleanups
   Thanks: https://github.com/bsutton

README.md

@@ -1,30 +1,9 @@
 # mailer
 
-
 **mailer** is an easy to use library for composing and sending emails in Dart.
 
 Mailer supports file attachments and HTML emails.
 
-
-## mailer2 and mailer3
-
-`mailer2` and `mailer3` on pub.dart are forks of this project.
-
-`mailer` was not well maintained and `mailer2` and `mailer3` had some important fixes.
-
-Currently `mailer` should include all known bug-fixes and AFAIK there is
-no reason to use `mailer2` or `mailer3`.
-
-
-## Dart2 support
-
-Support for dart2 has been added in version ^1.2.0  
-
-Version ^2.0.0 is a rewrite (it too supports dart1.x and dart2).
-
-Even though the API for ^2.0.0 has slightly changed, *most* programs will probably
-continue to work with deprecation warnings.
-
 ## SMTP definitions
 
 Mailer provides configurations for a few common SMTP servers.
@@ -36,7 +15,8 @@ Please create merge requests for missing configurations.
 * Export the newly created SMTP server in `lib/smtp_server.dart`
 * Create a pull request.
 
-In a lot of cases you will find a configuration in [legacy.dart](https://github.com/kaisellgren/mailer/blob/v2/lib/legacy.dart)
+In a lot of cases you will find a configuration
+in [legacy.dart](https://github.com/kaisellgren/mailer/blob/v2/lib/legacy.dart)
 
 ## Features
 
@@ -53,8 +33,8 @@ In a lot of cases you will find a configuration in [legacy.dart](https://github.
 * Correct encoding of non ASCII mail addresses.
 * Reintegrate address validation from version 1.*
 * Improve Header types.  (see [ir_header.dart](lib/src/smtp/internal_representation/ir_header.dart))  
-We should choose the correct header based on the header name.  
-Known headers (`list-unsubscribe`,...) should have their own subclass.
+  We should choose the correct header based on the header name.  
+  Known headers (`list-unsubscribe`,...) should have their own subclass.
 * Improve documentation.
 
 ## Examples
@@ -76,7 +56,7 @@ main() async {
   // final smtpServer = SmtpServer('smtp.domain.com');
   // See the named arguments of SmtpServer for further configuration
   // options.  
-  
+
   // Create our message.
   final message = Message()
     ..from = Address(username, 'Your name')
@@ -97,8 +77,8 @@ main() async {
     }
   }
   // DONE
-  
-  
+
+
   // Let's send another message using a slightly different syntax:
   //
   // Addresses without a name part can be set directly.
@@ -109,32 +89,37 @@ main() async {
   // `new Address('[email protected]')` is equivalent to
   // adding the mail address as `String`.
   final equivalentMessage = Message()
-      ..from = Address(username, 'Your name')
-      ..recipients.add(Address('[email protected]'))
-      ..ccRecipients.addAll([Address('[email protected]'), '[email protected]'])
-      ..bccRecipients.add('[email protected]')
-      ..subject = 'Test Dart Mailer library :: 😀 :: ${DateTime.now()}'
-      ..text = 'This is the plain text.\nThis is line 2 of the text part.'
-      ..html = "<h1>Test</h1>\n<p>Hey! Here's some HTML content</p>";
-
+    ..from = Address(username, 'Your name 😀')
+    ..recipients.add(Address('[email protected]'))
+    ..ccRecipients.addAll([Address('[email protected]'), '[email protected]'])
+    ..bccRecipients.add('[email protected]')
+    ..subject = 'Test Dart Mailer library :: 😀 :: ${DateTime.now()}'
+    ..text = 'This is the plain text.\nThis is line 2 of the text part.'
+    ..html = '<h1>Test</h1>\n<p>Hey! Here is some HTML content</p><img src="cid:[email protected]"/>'
+    ..attachments = [
+      FileAttachment(File('exploits_of_a_mom.png'))
+        ..location = Location.inline
+        ..cid = '<[email protected]>'
+    ];
+
   final sendReport2 = await send(equivalentMessage, smtpServer);
-  
+
   // Sending multiple messages with the same connection
   //
   // Create a smtp client that will persist the connection
   var connection = PersistentConnection(smtpServer);
-  
+
   // Send the first message
   await connection.send(message);
-  
+
   // send the equivalent message
   await connection.send(equivalentMessage);
-  
+
   // close the connection
   await connection.close();
-
 }
 ```
 
 ## License
+
 This library is licensed under MIT.

lib/src/entities/address.dart

@@ -1,16 +1,17 @@
 class Address {
-  String? name;
-  String? mailAddress;
+  final String? name;
+  final String mailAddress;
 
-  Address([this.mailAddress, this.name]);
+  const Address(this.mailAddress, [this.name]);
+
+  /// The name used to output to SMTP server.
+  /// Implementation can override it to pre-process the name before sending.
+  /// For example, providing a default name for certain address, or quoting it.
+  String? get sanitizedName => name;
+  /// The address used to output to SMTP server.
+  /// Implementation can override it to pre-process the address before sending
+  String get sanitizedAddress => mailAddress;
 
-  /// Generates an address that must conform to RFC 5322.
-  /// For example, `name <[email protected]>`, `<[email protected]>`
-  /// and `foo.domain.com`.
   @override
-  String toString() {
-    var fromName = name ?? '';
-    // ToDo base64 fromName (add _IRMetaInformation as argument)
-    return '$fromName <$mailAddress>';
-  }
+  String toString() => "${name ?? ''} <$mailAddress>";
 }

lib/src/entities/attachment.dart

@@ -16,11 +16,15 @@ enum Location {
 /// Represents a single email attachment.
 ///
 /// You may specify a [File], a [Stream] or just a [String] of [data].
-/// [cid] allows you to specify the content id.
+/// [cid] allows you to specify the content id for html inlining.
 ///
 /// When [location] is set to [Location.inline] The attachment (usually image)
 /// can be referenced using:
 /// `cid:yourCid`.  For instance: `<img src="cid:yourCid" />`
+///
+/// [cid] must contain an `@` and be inside `<` and `>`.
+/// The cid: `<[email protected]>` can then be referenced inside your html as:
+/// `<img src="cid:[email protected]">`
 abstract class Attachment {
   String? cid;
   Location location = Location.attachment;

lib/src/smtp/capabilities.dart

@@ -1,3 +1,17 @@
+import 'package:meta/meta.dart';
+
+@visibleForTesting
+Capabilities capabilitiesForTesting(
+    {bool startTls = false,
+    bool smtpUtf8 = false,
+    bool authPlain = true,
+    bool authLogin = false,
+    bool authXoauth2 = false,
+    List<String> all = const <String>[]}) {
+  return Capabilities._values(
+      startTls, smtpUtf8, authPlain, authLogin, authXoauth2, all);
+}
+
 class Capabilities {
   final bool startTls;
   final bool smtpUtf8;

lib/src/smtp/internal_representation/conversion.dart

@@ -1,6 +1,10 @@
 import 'dart:async';
 import 'dart:convert' as convert;
 
+import 'package:logging/logging.dart';
+
+final Logger _logger = Logger('conversion');
+
 const String eol = '\r\n';
 
 List<int> to8(String s) => convert.utf8.encode(s);
@@ -71,22 +75,31 @@ Iterable<List<int>> split(List<int> data, int maxLength,
 Stream<List<int>> _splitS(
     Stream<List<int>> dataS, int splitOver, int maxLength) {
   var currentLineLength = 0;
+  var insertEol = false;
 
   var sc = StreamController<List<int>>();
   void processData(List<int> data) {
+    _logger.finest('_splitS: <- ${data.length} bytes  currentLineLength: $currentLineLength');
     if (data.length + currentLineLength > maxLength) {
       var targetLength = maxLength ~/ 2;
       if (targetLength + currentLineLength > maxLength) {
         targetLength = maxLength - currentLineLength;
       }
+      _logger.finest('_splitS: > maxLength ($maxLength) Splitting into $targetLength parts');
       split(data, targetLength, avoidUtf8Cut: false).forEach(processData);
     } else if (data.length + currentLineLength > splitOver) {
+      _logger.finest('_splitS: inside splitOver ($splitOver) and maxLength ($maxLength) window.');
       // We are now over splitOver but not too long.  Perfect.
+      if (insertEol) sc.add(eol8);
       sc.add(data);
-      sc.add(eol8);
       currentLineLength = 0;
+      insertEol = true;
     } else {
+      _logger.finest('_splitS: below splitOver ($splitOver).');
       // We are still below splitOver
+      if (insertEol) sc.add(eol8);
+      insertEol = false;
+
       sc.add(data);
       currentLineLength += data.length;
     }

lib/src/smtp/internal_representation/internal_representation.dart

@@ -2,6 +2,7 @@ import 'dart:async';
 import 'dart:convert' as convert;
 
 import 'package:intl/intl.dart';
+import 'package:logging/logging.dart';
 import 'package:mailer/src/utils.dart';
 
 import '../../entities/address.dart';

lib/src/smtp/internal_representation/ir_content.dart

@@ -41,12 +41,14 @@ abstract class _IRContentPart extends _IRContent {
   late Iterable<_IRContent> _content;
 
   List<int> _boundaryStart(String boundary) => to8('--$boundary$eol');
+
   List<int> _boundaryEnd(String boundary) => to8('--$boundary--$eol');
 
   // We don't want to expose the number of sent emails.
   // Only use the counter, if milliseconds hasn't changed.
   static int _counter = 0;
   static int? _prevTimestamp;
+
   static String _buildBoundary() {
     var now = DateTime.now().millisecondsSinceEpoch;
     if (now != _prevTimestamp) _counter = 0;
@@ -84,7 +86,7 @@ Iterable<T> _follow<T>(T t, Iterable<T> ts) sync* {
 
 class _IRContentPartMixed extends _IRContentPart {
   _IRContentPartMixed(Message message, Iterable<_IRHeader> header) {
-    var attachments = message.attachments ;
+    var attachments = message.attachments;
     var attached = attachments.where((a) => a.location == Location.attachment);
 
     _active = attached.isNotEmpty;
@@ -155,7 +157,7 @@ class _IRContentAttachment extends _IRContent {
     _header.add(_IRHeaderText('content-transfer-encoding', 'base64'));
 
     if ((_attachment.cid ?? '').isNotEmpty) {
-      _header.add(_IRHeaderText('content-id', _attachment.cid));
+      _header.add(_IRHeaderText('content-id', _attachment.cid!));
     }
 
     var fnSuffix = '';
@@ -173,7 +175,7 @@ class _IRContentAttachment extends _IRContent {
 enum _IRTextType { plain, html }
 
 class _IRContentText extends _IRContent {
-  String? _text;
+  String _text = '';
 
   _IRContentText(
       String? text, _IRTextType textType, Iterable<_IRHeader> header) {