Update examples and documentation

Author: mobizt

README.md

@@ -6,7 +6,7 @@
 
 [![GitHub Sponsors](https://img.shields.io/github/sponsors/mobizt?logo=github)](https://github.com/sponsors/mobizt)
 
-Revision `2025-01-22T03:55:52Z`
+Revision `2025-01-23T06:30:53Z`
 
 ## Table of Contents
 
@@ -361,6 +361,8 @@ For the concept and basic usage understanding, you should read this documentatio
 > [!IMPORTANT]  
 > For new `Firebase` users, please read the [Project Preparation and Setup](#project-preparation-and-setup) section.
 
+The [beare minimun examples](https://github.com/mobizt/FirebaseClient/blob/main/examples/BareMinimum/) provides the minimum code that requires by this library.
+
 - ### Authentication
 
 The authentication classes provide the authentication data for authentication and authorization using service account, sign-in credentials and auth tokens.
@@ -378,7 +380,7 @@ The authorization token will be refreshed or re-created automatically as long as
 > 
 > Anyway, library also provides the option for less or non-secure usage which no authorization tokens are involved i.e. using database secret (`LegacyToken`) for Realtime database and using no authorization token (`NoAuth`) if the security rules are allowed (see the [Project Preparation and Setup](#project-preparation-and-setup) section). 
 > 
-> You can get started using this library with these [simple Realtime database examples](https://github.com/mobizt/FirebaseClient/blob/main/examples/RealtimeDatabase/Simple) which using database secret and no token, which are similar to the other legacy Firebase library usage. 
+> You can get started using this library with these [beare minimun examples](https://github.com/mobizt/FirebaseClient/blob/main/examples/BareMinimum/) or these [simple Realtime database examples](https://github.com/mobizt/FirebaseClient/blob/main/examples/RealtimeDatabase/Simple) which using database secret and no token, which are similar to the other legacy Firebase library usage. 
 >
 > For secure and more elaborate usages, you have to read the documentation thouroughly and follow the library provided examples to get familiar with the library usage.
 

examples/BareMinimum/Async/Callback/AllServices/AllServices.ino

@@ -1,75 +1,171 @@
 /**
  * ABOUT:
+ *
  * The beare minimum code example for all Firebase services in async mode with callback function.
+ *
+ * The steps which are generally required and explained below.
+ *
+ * Step 1. Include the network, SSL client and Firebase libraries.
+ * ===============================================================
+ *
+ * Step 2. Define the user functions that requred for the library usage.
+ * =====================================================================
+ *
+ * Step 3. Define the network config (identifier) class.
+ * =====================================================
+ * Why this is existed and Is it used for?
+ *
+ * This library supports many types of network interfaces.
+ * Then we have to know which type of network is currently inused and how to check the connection status
+ * and how to re-connect the network.
+ *
+ * This reduces the user code to maintain the network connection and management and also provides
+ * the networks switching or bridge usage.
+ *
+ * Step 4. Define the authentication config (identifier) class.
+ * ============================================================
+ * In the Firebase/Google Cloud services REST APIs, the auth tokens are used for authentication/authorization.
+ *
+ * The auth token is a short-lived token that will be expired in 60 minutes and need to be refreshed or re-created when it expired.
+ *
+ * There can be some special use case that some services provided the non-authentication usages e.g. using database secret
+ * in Realtime Database, setting the security rules in Realtime Database, Firestore and Firebase Storage to allow public read/write access.
+ *
+ * The UserAuth (user authentication with email/password) is the basic authentication for Realtime Database,
+ * Firebase Storage and Firestore services except for some Firestore services that involved with the Google Cloud services.
+ *
+ * It stores the email, password and API keys for authentication process.
+ *
+ * In Google Cloud services e.g. Cloud Storage and Cloud Functions, the higest authentication level is required and
+ * the ServiceAuth class (OAuth2.0 authen) and AccessToken class will be use for this case.
+ *
+ * While the CustomAuth provides the same authentication level as user authentication unless it allows the custom UID, scopes and claims.
+ *
+ * The internal process of some authentication types e.g. ServiceAuth and CustomAuth, requires the signed JWT token generation process.
+ * Because of it uses large memory and high cpu usage while signing the JWT token, this process requires another class to work
+ * called JWT processor which defined as a static object for global usage to use Heap instead of stack memory.
+ *
+ * As the valid timestamp is required in JWT token signing process, the time status callback function is required
+ * and assigned to the ServiceAuth and CustomAuth classes constructors.
+ *
+ * Step 5. Define the authentication handler class.
+ * ================================================
+ * The FirebaseApp actually works as authentication handler.
+ * It also maintains the authentication or re-authentication when you place the FirebaseApp::loop() inside the main loop.
+ *
+ * Step 6. Define the SSL client.
+ * ==============================
+ * It handles server connection and data transfer.
+ *
+ * In this beare minimum examples we use only one SSL client for all process.
+ * In some use cases e.g. Realtime Database Stream connection, you may have to define the SSL client for it separately.
+ *
+ * Step 7. Define the Async Client.
+ * ================================
+ * This is the class that is used with the functions where the server data transfer is involved.
+ * It stores all sync/async taks in its queue.
+ *
+ * It requires the SSL client and network config (identifier) data for its class constructor for
+ * server connection and data transfer.
+ *
+ * Step 8. Define the class that provides the Firebase/Google Cloud services.
+ * ==========================================================================
+ * The Firebase/Google Cloud services classes provide the member functions that works with AsyncClient.
+ *
+ * Step 9. Define the AsyncResult class
+ * ====================================
+ * This keeps the processing result when it assigned to any sync/async w/o callback functions.
+ *
+ * Step 10. Start the authenticate process.
+ * ========================================
+ * In this step, it actually adds the authentication task to the AsyncClient queue which will be processed later.
+ * The result/status will send to the callback function in case of async with callback usage or stores in the AsyncResult object
+ * in case asynce without callback and sync usages.
+ *
+ * This allows us to use different authentications for each Firebase/Google Cloud services with different
+ * FirebaseApp (authentication handler).
+ *
+ * Please avoid placing your code that uses large memory and cpu time inside the callback function to prevent the stack overflow and
+ * nested callback calls.
+ *
+ * Step 11. Bind the FirebaseApp (authentication handler) with your Firebase/Google Cloud services classes.
+ * ========================================================================================================
+ * This allows us to use different authentications for each Firebase/Google Cloud services.
+ *
+ * It is easy to bind/unbind/chanhe the authentication for authentication for different Firebase/Google Cloud services APIs.
+ *
+ * Step 12. Set the Realtime Database URL (for Realtime Database only)
+ * ===================================================================
+ *
+ * Step 13. Maintain the authentication (async) task in the loop.
+ * ==============================================================
+ * This is required for authentication/re-authentication process.
+ *
+ * When the UserAuth and CustomAuth classes are used, the JWT.loop() will be required to run in the loop().
+ *
+ * Step 14. Maintain the Firebase/Google Cloud services async tasks in the loop.
+ * =============================================================================
+ * This depends on how the AsyncClient class was used.
+ *
+ * If only one AsyncClient object was used in all tasks i.e.authentication and
+ * Firbase/Google Cloud services tasks, then these tasks stored in
+ * only one AsyncClient's queue then the Step 13 is enough and Step 14 is not necessary.
+ *
+ * Step 15. Checking the authentication status before use.
+ * =======================================================
+ * Before calling the Firebase/Google Cloud services functions, the FirebaseApp::ready() of authentication handler that bined to it
+ * should return true.
+ *
+ * Step 16. Process the sync/async w/o callback results in the end of the loop.
+ * ============================================================================
+ * This requires only when using library in sync/async w/o callback modes to process the information in its AsyncResult.
  */
 
-// 1. Include the network, SSL client and Firebase libraries.
-// ==========================================================
+// Step 1
 #include <Arduino.h>
 #include <WiFi.h>
 #include <WiFiClientSecure.h>
 #include <FirebaseClient.h>
 
-// 2. Define the function prototypes of functions we will use.
-// ===========================================================
+// Step 2
 void timeStatusCB(uint32_t &ts);
 void asyncCB(AsyncResult &aResult);
 void printResult(AsyncResult &aResult);
 void getMsg(Messages::Message &msg);
 
-// 3. Define the network config (identifier) class.
-// ================================================
-// The DefaultNetwork class object will provide the WiFi network identifier for ESP32/ESP8266 and
-// any WiFi capable devices.
-// Why we have to define this? It is because this library supports many types of network interfaces.
-// The library have to know which type of network you are using and used for connecting status checking and
-// performs network re-connection if neccessary.
+// Step 3
 DefaultNetwork network;
 
-// 4. Define the authentication config (identifier) class.
-// =======================================================
-// In this case the ServiceAuth class (OAuth2.0 authen) can be used for all services 
-// especially Cloud Storage and Cloud Functions required this authentication type.
-// The timeStatusCB is the callback function to set the library timestamp for internal process.
+// Step 4
 ServiceAuth sa_auth(timeStatusCB, "CLIENT_EMAIL", "PROJECT_ID", "PRIVATE_KEY", 3000);
 
-// 5. Define the authentication handler class.
-// ===========================================
-// It handles and maintains (re-authenticate in case auth token was expired in 60 min) 
-// the Firebase authentication process for you.
-// Actually you can define different FirebaseApps for each Firebase/Google Cloud services. 
+// Step 5
 FirebaseApp app;
 
-// 6. Define the SSL client.
-// =========================
-// In this case we use only one SSL client for all process.
+// Step 6
 WiFiClientSecure ssl_client;
 
-// 7. Define the Async Client.
-// ===========================
-// We have to use it for all processes.
-// The getNetwork(network) in Step 3 and SSL client in Step 6 are required for Async Client
-// for server connection and data transfer.
+// Step 7
 using AsyncClient = AsyncClientClass;
 AsyncClient aClient(ssl_client, getNetwork(network));
 
-// 8. Define the class that provides the Firebase service API.
-// ===========================================================
+// Step 8
 RealtimeDatabase Database;
 Messaging messaging;
 Firestore::Documents Docs;
 Storage storage;
 CloudStorage cstorage;
 CloudFunctions cfunctions;
 
+// Step 9 (not used in this async with callback usage)
+// AsyncResult myResult;
+
 bool onetimeTest = false;
 
 void setup()
 {
     Serial.begin(115200);
 
-    // 9. Setup network and connect
-    // ============================
     WiFi.begin("WIFI_AP", "WIFI_PASSWORD");
 
     Serial.print("Connecting to Wi-Fi");
@@ -86,55 +182,36 @@ void setup()
     // Skip certificate verification
     ssl_client.setInsecure();
 
-    // 10. Start authenticate process.
-    // ===============================
-    // It actually adds the authentication task to the AsyncClient queue which will be processed later.
-    // The result/status will send to the callback function "asyncCB".
+    // Step 10
     initializeApp(aClient, app, getAuth(sa_auth), asyncCB, "authTask");
 
-    // 11. Transfer or bind the authentication credentials
-    // ==================================================== 
-    // The auth credentials from FirebaseApp will be applied to the Firebase/Google Cloud services classes
-    // that defined in Step 8.
+    // Step 11
     app.getApp<RealtimeDatabase>(Database);
     app.getApp<Messaging>(messaging);
     app.getApp<Firestore::Documents>(Docs);
     app.getApp<Storage>(storage);
     app.getApp<CloudStorage>(cstorage);
     app.getApp<CloudFunctions>(cfunctions);
 
-    // 12. Set your database URL (requires only for Realtime Database)
-    // ===============================================================
+    // Step 12
     Database.url("DATABASE_URL");
 }
 
 void loop()
 {
-    // 13. Calling the JWT token processor in the loop
-    // ===============================================
-    // This handles the internal processes (JWT token generation) for ServiceAuth 
-    // and CustomAuth authentications.
+    // Step 13
     JWT.loop(app.getAuth());
-
-    // 14. Maintain the authentication (async) task in the loop
-    // ========================================================
-    // This required for authentication/re-authentication.
     app.loop();
 
-    // 15. Maintain the Firebase service async tasks in the loop.
-    // ==========================================================
-    // This is not neccessary if the same AsyncClient or aClient provided for 
-    // all authentication processes and Firebase services functions, calling app.loop()
-    // is enough.
+    // Step 14
     Database.loop();
     messaging.loop();
     Docs.loop();
     storage.loop();
     cstorage.loop();
     cfunctions.loop();
 
-    // 16. Checking the authentication status before calling Firebase services API.
-    // ============================================================================
+    // Step 15
     if (app.ready() && !onetimeTest)
     {
         onetimeTest = true;
@@ -163,15 +240,16 @@ void loop()
         // Cloud Functions call function.
         cfunctions.call(aClient, GoogleCloudFunctions::Parent("PROJECT_ID", "PROJECT_LOCATION"), "helloWorld", "test", asyncCB, "Functions_CallTask");
     }
+
+    // Step 16 (not used in this async with callback usage)
+    // printResult(myResult);
 }
 
-// 17. Defined the auxiliary function required to get the timestamp for internal JWT token signing process.
-// ========================================================================================================.
 void timeStatusCB(uint32_t &ts)
 {
+    // The valid timestamp is needed for signed JWT token process when ServiceAuth and CustomAuth classes are used.
     if (time(nullptr) < FIREBASE_DEFAULT_TS)
     {
-
         configTime(3 * 3600, 0, "pool.ntp.org");
         while (time(nullptr) < FIREBASE_DEFAULT_TS)
         {
@@ -181,14 +259,8 @@ void timeStatusCB(uint32_t &ts)
     ts = time(nullptr);
 }
 
-// 18. The callback function that will be called when the information/error/data 
-// from the auth and Firebase processes are available.
-// =============================================================================
 void asyncCB(AsyncResult &aResult) { printResult(aResult); }
 
-// 19. Optional for debugging.
-// ===========================
-// The auxiliary function that we will print all information that obtained from the processes.
 void printResult(AsyncResult &aResult)
 {
     if (aResult.isEvent())
@@ -204,8 +276,6 @@ void printResult(AsyncResult &aResult)
         Firebase.printf("task: %s, payload: %s\n", aResult.uid().c_str(), aResult.c_str());
 }
 
-// 20 The auxiliary function to create the message to send.
-// ========================================================
 void getMsg(Messages::Message &msg)
 {
     msg.topic("test");