Merge branch 'v1.0.2' into main

CHANGELOG.md

@@ -71,4 +71,10 @@
 
 ## v1.0.1:
 > Release date: 04/Jul/2021
-* Fix Notion-Version header missing
+* Fix Notion-Version header missing
+
+## v1.0.2:
+> Release date: 05/Jul/2021
+* Fix warnings for documentation
+* Improve documentation
+* Add contribution rules

README.md

@@ -5,6 +5,19 @@ Notion API client for dart.
 
 See the [ROADMAP](ROADMAP.md) file to see what is coming next.
 
+- [Usage](#usage)
+  - [`NotionClient` class](#notionclient-class)
+  - [Individual classes](#individual-classes)
+  - [A few examples](#a-few-examples)
+    - [Append blocks children](#append-blocks-children)
+    - [Create a page](#create-a-page)
+- [Contributions](#contributions)
+  - [Rules](#rules)
+  - [Tests](#tests)
+    - [Example:](#example)
+- [Next release](#next-release)
+  - [v1.1.0:](#v110)
+
 # Usage
 **Important**: The methods return a `NotionResponse`. You can find how to use it in its [documentation][1].
 
@@ -28,8 +41,8 @@ NotionDatabasesClient databases = NotionDatabasesClient(token: 'YOUR_TOKEN');
 databases.fetchAll();
 ```
 
-## Some examples
-_To see more examples [go here](example/example.md)._
+## A few examples
+_To see more examples [go here](https://github.com/jonathangomz/notion_api/blob/main/example/example.md)._
 
 ### Append blocks children
 ```dart
@@ -66,15 +79,46 @@ Page page = Page(
 notion.pages.create(page);
 ```
 
+# Contributions
+Please help, I don't even know if what I'm doing is right.
+
+## Rules
+Some rules to follow:
+1. Please follow the dart convention format:
+   1. [Effective dart](https://dart.dev/guides/language/effective-dart)
+   2. [`dart format`](https://dart.dev/tools/dart-format)
+2. If you are adding a new function, please also add the documentation.
+3. If you are adding a new parameters, please also add it to the current documentation.
+4. (**Optional**) Run the tests to know that everything is working just fine ([See how run the tests](#tests)).
+   * This is optional because sometimes the tests fail on GitHub actions so anyway I will check this on my computer.
+
+## Tests
+To be able to run the tests you will have to have a `.env` file on the root directory with the next variables:
+* TOKEN: The secret token.
+* TEST_DATABASE_ID: The database id where you will be working on.
+* TEST_PAGE_ID: Some page id inside the database specified above.
+* TEST_BLOCK_ID: Some block id inside the page specified above.
+
+### Example:
+_The values are not valid of course._
+```
+TOKEN=secret_Oa24V8FbJ49JluJankVOQihyLiMXwqSQeeHuSFobQDW
+TEST_DATABASE_ID=366da3d646bb458128071fdb2fbbf427
+TEST_PAGE_ID=c3b53019-4470-443b-a141-95a3a1a44g60
+TEST_BLOCK_ID=c8hac4bb32af48889228bf483d938e34
+```
+
 # Next release
 ## v1.1.0:
 > Release date: 10/Jul/2021
 * Add more blocks for `(PATCH): block children` endpoint
   * `BulletedList` block
   * `NumberedList` block
   * `Toggle` block
-
-# Contributions
-Please help, I don't even know if what I'm doing is right.
+* Add `Children.with(List<Block> blocks)` constructor
+* Add singleton (_if possible_)
+* Add `final` for override types to not allow change the field:
+  * Objects
+  * Blocks
 
 [1]:https://pub.dev/documentation/notion_api/1.0.0-beta1/responses_notion_response/NotionResponse-class.html

ROADMAP.md

@@ -8,9 +8,19 @@
   * `BulletedList` block
   * `NumberedList` block
   * `Toggle` block
-* Add singleton
+* Add `Children.with(List<Block> blocks)` constructor
+* Add singleton (_if possible_)
+* Add `final` for override types to not allow change the field:
+    * Objects
+    * Blocks
 
-## v1.0.1:
+## v1.0.2: ✅
+> Release date: 05/Jul/2021
+* Fix warnings for documentation
+* Improve documentation
+* Add contribution rules
+
+## v1.0.1: ✅
 > Release date: 04/Jul/2021
 * Fix Notion-Version header missing
 

example/example.md

@@ -161,21 +161,39 @@ notion.blocks.append(
 #### To do
 ##### Code
 ```dart
-Children children = 
-  Children(
-    toDo: [
-      ToDo(text: Text('This is a todo item A')),
-      ToDo(
-        texts: [
-          Text('This is a todo item'),
-          Text(
-            'B',
-            annotations: TextAnnotations(bold: true),
-          ),
-        ],
-      ),
-    ],
-  );
+// Create children instance:
+// * Old way
+// Children children = 
+//   Children(
+//     toDo: [
+//       ToDo(text: Text('This is a todo item A')),
+//       ToDo(
+//         texts: [
+//           Text('This is a todo item'),
+//           Text(
+//             'B',
+//             annotations: TextAnnotations(bold: true),
+//           ),
+//         ],
+//       ),
+//     ],
+//   );
+//
+// * New way
+Children children =
+  Children().addAll([
+    ToDo(text: Text('This is a todo item A')),
+    ToDo(
+      texts: [
+        Text('This is a todo item'),
+        Text(
+          'B',
+          annotations: TextAnnotations(bold: true),
+        ),
+      ],
+    ),
+  ],
+);
 
 // Send the instance to Notion
 notion.blocks.append(

lib/notion.dart

@@ -28,11 +28,11 @@ class NotionClient {
   /// Require the [token] to authenticate the requests. Also can receive the API [version] where to make the calls, which is the latests by default (v1); and the [dateVersion] which is by default "2021-05-13" (the latest at 04/07/2021).
   ///
   /// This class is used as the main entry point for all clients. From the instances of this class any other client can be used.
-  NotionClient(
-      {required String token,
-      String version: latestVersion,
-      String dateVersion: latestDateVersion})
-      : this.pages = NotionPagesClient(
+  NotionClient({
+    required String token,
+    String version: latestVersion,
+    String dateVersion: latestDateVersion,
+  })  : this.pages = NotionPagesClient(
             token: token, version: version, dateVersion: dateVersion),
         this.databases = NotionDatabasesClient(
             token: token, version: version, dateVersion: dateVersion),

lib/notion_blocks.dart

@@ -14,20 +14,22 @@ class NotionBlockClient {
   /// The API version.
   String _v;
 
+  /// The API date version.
+  ///
+  /// It's not the same as the API version.
+  String _dateVersion;
+
   /// The path of the requests group.
   String _path = 'blocks';
 
-  /// Notion versioning. For reference, see: [Notion versioning](https://developers.notion.com/reference/versioning)
-  String _dateVersion;
-
   /// Main Notion block client constructor.
   ///
   /// Require the [token] to authenticate the requests, and the API [version] where to make the calls, which is the latests by default (v1).
-  NotionBlockClient(
-      {required String token,
-      String version: latestVersion,
-      String dateVersion: latestDateVersion})
-      : this._token = token,
+  NotionBlockClient({
+    required String token,
+    String version: latestVersion,
+    String dateVersion: latestDateVersion,
+  })  : this._token = token,
         this._v = version,
         this._dateVersion = dateVersion;
 

lib/notion_databases.dart

@@ -11,7 +11,9 @@ class NotionDatabasesClient {
   /// The API version.
   String _v;
 
-  /// Notion versioning. For reference, see: [Notion versioning](https://developers.notion.com/reference/versioning)
+  /// The API date version.
+  ///
+  /// It's not the same as the API version.
   String _dateVersion;
 
   /// The path of the requests group.
@@ -20,8 +22,11 @@ class NotionDatabasesClient {
   /// Main Notion database client constructor.
   ///
   /// Require the [token] to authenticate the requests, and the API [version] where to make the calls, which is the latests by default (v1).
-  NotionDatabasesClient({required String token, String version: latestVersion, String dateVersion: latestDateVersion})
-      : this._token = token,
+  NotionDatabasesClient({
+    required String token,
+    String version: latestVersion,
+    String dateVersion: latestDateVersion,
+  })  : this._token = token,
         this._v = version,
         this._dateVersion = dateVersion;
 

lib/notion_pages.dart

@@ -14,7 +14,9 @@ class NotionPagesClient {
   /// The API version.
   String _v;
 
-  /// Notion versioning. For reference, see: [Notion versioning](https://developers.notion.com/reference/versioning)
+  /// The API date version.
+  ///
+  /// It's not the same as the API version.
   String _dateVersion;
 
   /// The path of the requests group.
@@ -23,11 +25,11 @@ class NotionPagesClient {
   /// Main Notion page client constructor.
   ///
   /// Require the [token] to authenticate the requests, and the API [version] where to make the calls, which is the latests by default (v1).
-  NotionPagesClient(
-      {required String token,
-      String version: latestVersion,
-      String dateVersion: latestDateVersion})
-      : this._token = token,
+  NotionPagesClient({
+    required String token,
+    String version: latestVersion,
+    String dateVersion: latestDateVersion,
+  })  : this._token = token,
         this._v = version,
         this._dateVersion = latestDateVersion;
 

lib/statics.dart

@@ -6,6 +6,7 @@ const String host = "api.notion.com";
 /// **Note:** At this point there is not a stable version yet.
 const String latestVersion = 'v1';
 
-
-/// The latest version of Notion API
+/// The latest date version of Notion API
+///
+/// See [Notion versioning](https://developers.notion.com/reference/versioning) for more information.
 const String latestDateVersion = '2021-05-13';

pubspec.yaml

@@ -1,6 +1,6 @@
 name: notion_api
 description: A wrapper for the public beta Notion API to manage it like a Notion SDK package for dart.
-version: 1.0.1
+version: 1.0.2
 homepage: https://github.com/jonathangomz/notion_api
 
 environment:

test/notion_api_test.dart

@@ -159,22 +159,21 @@ void main() {
 
       NotionResponse res = await blocks.append(
         to: testBlockId as String,
-        children: Children(
-          heading: Heading(text: Text('Test')),
-          paragraph: Paragraph(
-            texts: [
-              Text('Lorem ipsum (A)'),
-              Text(
-                'Lorem ipsum (B)',
-                annotations: TextAnnotations(
-                  bold: true,
-                  underline: true,
-                  color: ColorsTypes.Orange,
-                ),
+        children: Children().add(Heading(text: Text('Test'))).add(
+              Paragraph(
+                texts: [
+                  Text('Lorem ipsum (A)'),
+                  Text(
+                    'Lorem ipsum (B)',
+                    annotations: TextAnnotations(
+                      bold: true,
+                      underline: true,
+                      color: ColorsTypes.Orange,
+                    ),
+                  ),
+                ],
               ),
-            ],
-          ),
-        ),
+            ),
       );
 
       expect(res.status, 200);
@@ -186,8 +185,8 @@ void main() {
 
       NotionResponse res = await blocks.append(
         to: testBlockId as String,
-        children: Children(
-          toDo: [
+        children: Children().addAll(
+          [
             ToDo(text: Text('This is a todo item A')),
             ToDo(
               texts: [