Merge pull request #1 from dart-pacotes/null-safety

Null safety

Author: joaomagfreitas

.gitignore

@@ -79,3 +79,6 @@ pubspec.lock
 
 # Ignore .metadata
 .metadata
+
+# Ignore test coverage
+coverage

README.md

@@ -1,3 +1,57 @@
 # pastebin
 
-A pure Dart Pastebin API Wrapper.
+A pure Dart Pastebin API Wrapper.
+
+## Features
+
+This package covers every endpoint disclosed in [Pastebin API documentation](https://pastebin.com/doc_api#9) (as of 16 May, 2022). The following table links the endpoints to the respective package functions:
+
+|API Endpoints|Function|Description|
+|-------------|--------|-----------|
+|[`/api/api_post.php` (2-8)](https://pastebin.com/doc_api#2)|[`paste(pasteText, options)`](https://pub.dev/documentation/pastebin/latest/pastebin/PastebinClient/paste.html)|Publishes a paste (with support for optional parameters) in Pastebin.|
+|[`/api/api_login.php` (9)](https://pastebin.com/doc_api#9)|[`apiUserKey(username, password)`](https://pub.dev/documentation/pastebin/latest/pastebin/PastebinClient/apiUserKey.html)|Retrieves and refreshes user API key (not developer key).|
+|[`/api/api_post.php` (10)](https://pastebin.com/doc_api#10)|[`pastes(userKey, limit=50)`](https://pub.dev/documentation/pastebin/latest/pastebin/PastebinClient/pastes.html)|Fetches an user pastes, with support for limiting how many pastes are returned.|
+|[`/api/api_post.php` (11)](https://pastebin.com/doc_api#11)|[`delete(pasteKey, userKey)`](https://pub.dev/documentation/pastebin/latest/pastebin/PastebinClient/delete.html)|Deletes an user paste.|
+|[`/api/api_post.php` (12)](https://pastebin.com/doc_api#12)|[`userInfo(userKey)`](https://pub.dev/documentation/pastebin/latest/pastebin/PastebinClient/userInfo.html)|Obtains user information and settings.|
+|[`/api/api_raw.php` (13)](https://pastebin.com/doc_api#13)|[`rawPaste(pasteKey, visibility, userKey)`](https://pub.dev/documentation/pastebin/latest/pastebin/PastebinClient/userInfo.html)|Gets the raw paste (full text) of a user paste.|
+|[`/api/raw.php` (14)](https://pastebin.com/doc_api#14)|[`rawPaste(pasteKey, visibility)`](https://pub.dev/documentation/pastebin/latest/pastebin/PastebinClient/userInfo.html)|Gets the raw paste (full text) of paste.|
+
+There is also support for multiple API key ingestion, a neat feature for making sure that pastes are published, even if you are rate limited by Pastebin.
+
+```dart
+// Using Official Pastebin API with a single API Dev Key
+var pastebinClient = withSingleApiDevKey(
+    apiDevKey: primaryApiDevKey,
+);
+
+// Using Official Pastebin API with multiple API Dev Key
+pastebinClient = withMultipleApiDevKey(
+    apiDevKeys: [
+        primaryApiDevKey,
+        fallbackApiDevKey1,
+        fallbackApiDevKey2,
+        ...
+        fallbackApiDevKeyN,
+    ],
+);
+```
+
+## Side Effects
+
+Powered by Dart null sound + [`dartz`](https://pub.dev/packages/dartz) monads, this package is free of null issues and side effects. This is to prevent the throw of any exception that may not be known and caught by developers, and to make sure that information is consistent by contract.
+
+Every HTTP request returns an `Either` monad that either returns the response result on the right hand, or `ResponseError` instance on the left hand that is typed to each possible Pastebin error (see available errors [here](https://pub.dev/documentation/pastebin/latest/pastebin/RequestError-class.html)).
+
+## Why use pastebin.dart?
+
+The main use case that inspired the development of this package, is to provide developers (mostly indie) a way to publish and read app logs for free.
+
+---
+
+### Bugs and Contributions
+
+Found any bug (including typos) in the package? Do you have any suggestion or feature to include for future releases? Please create an issue via GitHub in order to track each contribution. Also, pull requests are very welcome!
+
+### Disclaimer
+
+This is not an official library/SDK implemented by the Pastebin team, but rather a developer implementation that uses it.

analysis_options.yaml

@@ -1,4 +1,3 @@
-include: package:effective_dart/analysis_options.yaml # https://pub.dartlang.org/packages/effective_dart
 linter: # Lint rules: http://dart-lang.github.io/linter/lints/
   rules:
     public_member_api_docs: false
@@ -17,4 +16,4 @@ linter: # Lint rules: http://dart-lang.github.io/linter/lints/
     unawaited_futures: false # https://dart-lang.github.io/linter/lints/unawaited_futures.html
     unnecessary_statements: true # http://dart-lang.github.io/linter/lints/unnecessary_statements.html
     unrelated_type_equality_checks: true # https://dart-lang.github.io/linter/lints/unrelated_type_equality_checks.html
-    valid_regexps: true # https://dart-lang.github.io/linter/lints/valid_regexps.html
+    valid_regexps: true # https://dart-lang.github.io/linter/lints/valid_regexps.html

example/pubspec.yaml

@@ -1,11 +1,10 @@
 name: example
 version: 1.0.0
+publish_to: none
 
 environment:
   sdk: ">=2.7.0 <3.0.0"
 
-dependencies:  
+dependencies:
   pastebin:
     path: ../
-
-dev_dependencies:

lib/src/models/expire_date.dart

@@ -12,7 +12,7 @@ enum ExpireDate {
   oneYear,
 }
 
-extension ExpireDateExtension on ExpireDate {
+extension ExpireDateExtension on ExpireDate? {
   static const Map<ExpireDate, String> values = {
     ExpireDate.never: 'N',
     ExpireDate.tenMinutes: '10M',
@@ -25,18 +25,19 @@ extension ExpireDateExtension on ExpireDate {
   };
 
   static ExpireDate parse(
-    final String expireDate,
-    final MapEntry<ExpireDate, String> Function() onError,
+    final String? expireDate,
+    final MapEntry<ExpireDate, String>? Function() onError,
   ) {
     return values.entries
-        .firstWhere((entry) => entry.value == expireDate, orElse: onError)
+        .firstWhere((entry) => entry.value == expireDate,
+            orElse: onError as MapEntry<ExpireDate, String> Function()?)
         .key;
   }
 
-  static ExpireDate tryParse(final String expireDate) =>
+  static ExpireDate tryParse(final String? expireDate) =>
       parse(expireDate, () => null);
 
-  String value() {
-    return values[this];
+  String? value() {
+    return values[this!];
   }
 }

lib/src/models/format.dart

@@ -258,7 +258,7 @@ enum Format {
   zxbasic
 }
 
-extension FormatExtension on Format {
+extension FormatExtension on Format? {
   static const Map<Format, String> values = {
     Format.cs4: '4cs',
     Format.acme6502: '6502acme',
@@ -517,17 +517,18 @@ extension FormatExtension on Format {
   };
 
   static Format parse(
-    final String format,
-    final MapEntry<Format, String> Function() onError,
+    final String? format,
+    final MapEntry<Format, String>? Function() onError,
   ) {
     return values.entries
-        .firstWhere((entry) => entry.value == format, orElse: onError)
+        .firstWhere((entry) => entry.value == format,
+            orElse: onError as MapEntry<Format, String> Function()?)
         .key;
   }
 
-  static Format tryParse(final String format) => parse(format, () => null);
+  static Format tryParse(final String? format) => parse(format, () => null);
 
-  String value() {
-    return values[this];
+  String? value() {
+    return values[this!];
   }
 }

lib/src/models/paste.dart

@@ -1,4 +1,3 @@
-import 'package:meta/meta.dart';
 import 'package:xml/xml.dart';
 
 import 'models.dart';
@@ -7,34 +6,34 @@ import 'models.dart';
 /// Models a Pastebin paste
 ///
 class Paste {
-  final String key;
+  final String? key;
 
   final DateTime createdDate;
 
   final DateTime expiredDate;
 
-  final String title;
+  final String? title;
 
-  final int sizeInBytes;
+  final int? sizeInBytes;
 
   final Visibility visibility;
 
   final Format format;
 
-  final Uri url;
+  final Uri? url;
 
-  final int hits;
+  final int? hits;
 
   const Paste({
-    @required this.createdDate,
-    @required this.expiredDate,
-    @required this.format,
-    @required this.hits,
-    @required this.key,
-    @required this.sizeInBytes,
-    @required this.title,
-    @required this.url,
-    @required this.visibility,
+    required this.createdDate,
+    required this.expiredDate,
+    required this.format,
+    required this.hits,
+    required this.key,
+    required this.sizeInBytes,
+    required this.title,
+    required this.url,
+    required this.visibility,
   });
 
   static List<Paste> fromXmlDocument(final XmlDocument xmlDocument) {
@@ -44,22 +43,22 @@ class Paste {
   static Paste fromXmlNode(final XmlNode xmlNode) {
     return Paste(
       createdDate: DateTime.fromMillisecondsSinceEpoch(
-        int.tryParse(xmlNode.getElement('paste_date')?.text),
+        int.tryParse(xmlNode.getElement('paste_date')!.text)!,
       ),
       expiredDate: DateTime.fromMillisecondsSinceEpoch(
-        int.tryParse(xmlNode.getElement('paste_expire_date')?.text),
+        int.tryParse(xmlNode.getElement('paste_expire_date')!.text)!,
       ),
       format: FormatExtension.tryParse(
         xmlNode.getElement('paste_format_short')?.text,
       ),
       visibility: VisibilityExtension.tryParse(
         xmlNode.getElement('paste_private')?.text,
       ),
-      hits: int.tryParse(xmlNode.getElement('paste_hits')?.text),
+      hits: int.tryParse(xmlNode.getElement('paste_hits')!.text),
       key: xmlNode.getElement('paste_key')?.text,
-      sizeInBytes: int.tryParse(xmlNode.getElement('paste_size')?.text),
+      sizeInBytes: int.tryParse(xmlNode.getElement('paste_size')!.text),
       title: xmlNode.getElement('paste_title')?.text,
-      url: Uri.tryParse(xmlNode.getElement('paste_url')?.text),
+      url: Uri.tryParse(xmlNode.getElement('paste_url')!.text),
     );
   }
 }

lib/src/models/paste_options.dart

@@ -6,15 +6,15 @@ import 'visibility.dart';
 /// Model for available settings of a [Paste] that can be set
 ///
 class PasteOptions {
-  final String apiUserKey;
+  final String? apiUserKey;
 
-  final String pasteName;
+  final String? pasteName;
 
-  final Format pasteFormat;
+  final Format? pasteFormat;
 
-  final Visibility pasteVisiblity;
+  final Visibility? pasteVisiblity;
 
-  final ExpireDate pasteExpireDate;
+  final ExpireDate? pasteExpireDate;
 
   const PasteOptions({
     this.apiUserKey,

lib/src/models/user_info.dart

@@ -1,4 +1,3 @@
-import 'package:meta/meta.dart';
 import 'package:xml/xml.dart';
 
 import 'models.dart';
@@ -7,47 +6,49 @@ import 'models.dart';
 /// Models the information and settings of Pastebin user
 ///
 class UserInfo {
-  final String userName;
+  final String? userName;
 
   final Format format;
 
   final ExpireDate expiration;
 
-  final Uri avatarUrl;
+  final Uri? avatarUrl;
 
   final Visibility visibility;
 
-  final String website;
+  final String? website;
 
-  final String email;
+  final String? email;
 
-  final String location;
+  final String? location;
 
-  final bool isPro;
+  final bool? isPro;
 
   const UserInfo({
-    @required this.avatarUrl,
-    @required this.email,
-    @required this.expiration,
-    @required this.format,
-    @required this.isPro,
-    @required this.location,
-    @required this.userName,
-    @required this.visibility,
-    @required this.website,
+    required this.avatarUrl,
+    required this.email,
+    required this.expiration,
+    required this.format,
+    required this.isPro,
+    required this.location,
+    required this.userName,
+    required this.visibility,
+    required this.website,
   });
 
   static UserInfo fromXmlNode(final XmlNode xmlNode) {
     return UserInfo(
-      avatarUrl: Uri.tryParse(xmlNode.getElement('user_avatar_url')?.text),
+      avatarUrl: Uri.tryParse(
+        xmlNode.getElement('user_avatar_url')?.text ?? '',
+      ),
       email: xmlNode.getElement('user_email')?.text,
       expiration: ExpireDateExtension.tryParse(
         xmlNode.getElement('user_expiration')?.text,
       ),
       format: FormatExtension.tryParse(
         xmlNode.getElement('user_format_short')?.text,
       ),
-      isPro: xmlNode.getElement('user_format_short')?.text?.endsWith('1'),
+      isPro: xmlNode.getElement('user_format_short')?.text.endsWith('1'),
       location: xmlNode.getElement('user_location')?.text,
       userName: xmlNode.getElement('user_name')?.text,
       visibility: VisibilityExtension.tryParse(

lib/src/models/visibility.dart

@@ -7,26 +7,27 @@ enum Visibility {
   private,
 }
 
-extension VisibilityExtension on Visibility {
+extension VisibilityExtension on Visibility? {
   static const Map<Visibility, String> values = {
     Visibility.public: '0',
     Visibility.unlisted: '1',
     Visibility.private: '2',
   };
 
   static Visibility parse(
-    final String visibility,
-    final MapEntry<Visibility, String> Function() onError,
+    final String? visibility,
+    final MapEntry<Visibility, String>? Function() onError,
   ) {
     return values.entries
-        .firstWhere((entry) => entry.value == visibility, orElse: onError)
+        .firstWhere((entry) => entry.value == visibility,
+            orElse: onError as MapEntry<Visibility, String> Function()?)
         .key;
   }
 
-  static Visibility tryParse(final String visibility) =>
+  static Visibility tryParse(final String? visibility) =>
       parse(visibility, () => null);
 
-  String value() {
-    return values[this];
+  String? value() {
+    return values[this!];
   }
 }