Edited documentation

psarin · Dec 16, 2023 · 36728ff · 36728ff
1 parent 64f95b5
commit 36728ff
Show file tree

Hide file tree

Showing 3 changed files with 30 additions and 10 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,4 +1,10 @@
 <!-- markdownlint-disable -->
+## 0.2.0 [released 2023.12.16]
+
+- Added various filter options
+- Bug fixes to get additional use cases working
+- Added additional documentation
+
 ## 0.1.0
 
 - Initial version.
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Pankaj Sarin
+Copyright (c) 2023 Pankaj Sarin
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
@@ -20,31 +20,34 @@ This library is a **WIP** inspired by the official [JavaScript SDK](https://gith
 >
 > [→ Learn more about authorization](https://developers.notion.com/docs/authorization).
 
+### Initialization
+
 Import and initialize a client using an **integration token** or an OAuth **access token**. The token can be imported from an Application / Session variable, the database, or an [environment variable](https://docs.lucee.org/guides/Various/system-properties.html) and best practice states it should **not** be hardcoded into the source code.
 
-This library can utilize two config files that you can place in the `config/` directory. The first is `settings.json` to hold your Notion API settings and authorization, and the second is `databases.json` to hold mappings to databases & pages you may want to access in  your code. See the `examples/config/` folder for samples.
+This library utilizes two config files that you can place in the `config/` directory. The first is `settings.json` to hold your Notion API settings and authorization, and the second is `databases.json` to hold mappings to databases & pages you may want to access in  your code. See the `examples/config/` folder for samples.
 
 ```js
-// Best to import token from Application variable, database, or environment variable
-// /examples/simple.cfm folder for examples how to use via Application variable.
-var NOTION_TOKEN = 'secret_token'; 
+// Best to import token from Application variable, database, or environment variable.
+// See /examples/simple.cfm folder for examples how to use via Application variable.
+var NOTION_TOKEN = 'secret_token';
 
 // Initializing a client
 var notion = new lib.NotionClient (auth: NOTION_TOKEN);
 ```
 
-Make a request to any Notion API endpoint.
+### Making requests
 
 > See the complete list of endpoints in the [API reference](https://developers.notion.com/reference).
 
 ```js
 // Request a list of users in workspace
 var listUsersResponse = notion.users.list();
+
 // Look at response
-writeDump(var = listUsersResponse);
+dump(listUsersResponse);
 ```
 
-Each method returns the response.
+Each method returns the response as per Notion API specification.
 
 <pre>
 {
@@ -64,7 +67,8 @@ Each method returns the response.
 }
 </pre>
 
-Endpoint parameters are grouped into a single object. You don't need to remember which parameters go in the path, query, or body.
+#### Endpoint parameters (e.g., filters, pagination)
+Endpoint parameters for requests are grouped into a single object. You don't need to remember which parameters go in the path, query, or body as the library will take care of this for you.
 
 ```js
 const myPage = notion.databases.query({
@@ -78,17 +82,26 @@ const myPage = notion.databases.query({
 })
 ```
 
+### Displaying data retrieved from Notion
+
+Data retrieved via the API can be converted to plain text or HTML easily by instantiating the blocks using the model representing the block. The library will attempt to transverse the block tree in order to convert all child blocks to their most appropriate representation.
+
+### Sending data to Notion
+
+Currently, the best way to add or edit objects in Notion is by manually constructing the PUT/PATCH/POST object specified in the Notion API and then using the library's BlockApi/PageApi/DatabaseApi/UserApi to send the data to Notion. The library does not convert your object to the schema required by Notion.
+
 ### Handling errors
 
 If the API returns an unsuccessful response, the returned response returns a simple error and the HTTP error response from server.
 
 TODO / NOT IMPLEMENTED: This library needs to better deal with error responses.
 
-<pre style="font-size:10px;"> 
+<pre style="font-size:10px;">
 The error contains properties from the response, and the most helpful is `code`. You can compare `code` to the values in the `APIErrorCode` object to avoid misspelling error codes.
 
 </pre>
 
+## Configuration
 ### Client options
 
 The `NotionClient` supports the following options on initialization. These options are all keys in the single constructor parameter.
@@ -105,6 +118,7 @@ This package supports the following minimum versions:
 - Runtime: `lucee >= 4.5 | acf >= 11`
 
 Testing has been done on the [Lucee CFML engine](https://lucee.org).
+
 ## Getting help
 
 If you have a question about the library, or are having difficulty using it, chat with the community in [Lucee Dev Forums](https://dev.lucee.org).