Merge pull request #3 from eryxcoop/error-handling

Response handling: Now responses can be general and custom porpuses.

.github/workflows/documentation.yml

@@ -0,0 +1,27 @@
+name: documentation
+
+on: [push]
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v3
+      - name: Install dependencies
+        run: |
+          pip install sphinx sphinx_rtd_theme myst_parser
+      - name: Sphinx build
+        run: |
+          sphinx-build docs _build
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/error-handling' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _build/
+          force_orphan: true

.github/workflows/test.yml

@@ -0,0 +1,21 @@
+# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions
+
+name: Runs All Unit tests
+
+on: [ push, pull_request ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [ '16.x', '18.x' ]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm install
+      - run: npm test

.gitignore

@@ -7,4 +7,5 @@
 /node_modules
 
 # ide
-.idea/*
+.idea/*
+docs/_build/*

README.md

@@ -1,10 +1,8 @@
-![image](https://img.shields.io/badge/JavaScript-323330?style=for-the-badge&logo=javascript&logoColor=F7DF1E)
-![image](https://img.shields.io/badge/npm-CB3837?style=for-the-badge&logo=npm&logoColor=white)
-
+![test workflow](https://github.com/github/docs/actions/workflows/test.yml/badge.svg) [![npm version](https://badge.fury.io/js/@eryxcoop%2Fappyx-comm.svg)](https://badge.fury.io/js/@eryxcoop%2Fappyx-comm)
 
 # Appyx-Comm
 
-![test workflow](https://github.com/github/docs/actions/workflows/test.yml/badge.svg)
+![image](https://img.shields.io/badge/JavaScript-323330?style=for-the-badge&logo=javascript&logoColor=F7DF1E) ![image](https://img.shields.io/badge/npm-CB3837?style=for-the-badge&logo=npm&logoColor=white)
 
 Communication package for javascript.
 
@@ -14,14 +12,7 @@ Communication package for javascript.
 $ npm i @eryxcoop/appyx-comm
 ```
 
-# Contribute
-
-In order to update npm package a new release must be created. Any new release must be named @eryxcoop/appyx-comm-{version}
-
-
-# Work to be done
+## Contribute
 
-- [x] Deploy library as a package in npm
-- [ ] Create sample project to show how the package works
-- [x] Add ApiClient
-- [ ] Add tests
+In order to update npm package a new release must be created. Any new release must be named
+@eryxcoop/appyx-comm-{version}

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,50 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+import sphinx_rtd_theme
+
+project = 'appyx-comm'
+copyright = '2024, Eryx'
+author = 'Eryx'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx_mdinclude",
+]
+
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# html_theme = "sphinx_rtd_theme"
+
+# -- Options for HTML output -------------------------------------------------
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "alabaster"
+html_theme_options = {
+    "description": "...",
+    "fixed_sidebar": True,
+    "badge_branch": "main",
+    "github_button": False,
+    "github_user": "eryxcoop",
+    "github_repo": "appyx-comm",
+    "show_powered_by": False,
+    "sidebar_collapse": False,
+}
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_static_path = ['_static']

docs/contributing.rst

@@ -0,0 +1,13 @@
+Contributing
+============
+
+To help speed up the review process please ensure the following:
+
+- The PR addresses an open issue.
+- All tests are passing locally with ``npm test``.
+- If adding a new feature you also add documentation.
+
+Developing
+----------
+
+Code!

docs/guide.rst

@@ -0,0 +1,114 @@
+``ApiClient``
+-------------
+
+wip
+
+
+``Requesters``
+-------------
+
+wip
+
+``Endpoints``
+-------------
+
+When you create and ``Endpoint`` you are defining where the request should be made, what type of request is it and what kind of responses should you expect.
+Your ApiClient will be able to execute the endpoint you created.
+For example, you can create an endpoint like this:
+
+.. code-block:: javascript
+  :linenos:
+
+    class ExampleEndpoint extends Endpoint{
+      url() {
+        return "example_url";
+      }
+
+      ownResponses() {
+        return [GetExampleResponse];
+      }
+
+      method() {
+        return this.constructor.getMethod();
+      }
+
+      needsAuthorization() {
+        return true;
+      }
+    }
+
+
+    // Now you can use it like this
+    const endpointToExample = new ExampleEndpoint();
+    const response = await client._callEndpoint(endpointToExample);
+
+``Responses``
+-------------
+
+Every time you make a call to the api, you will (usually) received a json response. Response is here for you to represent that response. That way you can easily tell
+you endpoint what kind of responses it should expect. You can use responses such as  ``SuccessfulApiResponse`` already given by the library or you can create your own to
+make use of its full potential and ask your response for specific information
+
+
+
+
+``Response Handler``
+-------------
+
+Response handlers are used to handle responses received from api requests. Every time you make a call you can indicate the way
+every expected response should be handled. For example, you can indicate that every successful response should be handled by running a function.
+
+
+.. code-block:: javascript
+  :linenos:
+
+    const customResponseHandler = ApiResponseHandler.for(
+        SuccessfulApiResponse,
+        (request) => {
+            doSomething();
+        },
+    );
+
+    // doSomething() will be called if exampleEndpoint returns a SuccessfulApiResponse
+    await client.exampleEndpoint(customResponseHandler);
+
+
+Sometimes you want to handle an specific response always in the same way. For example, you may want to handle every 401 response by authenticating the user again. To do this
+you have to indicate all your general responses handlers in the client constructor. For example:
+
+.. code-block:: javascript
+  :linenos:
+
+    const generalResponsesHandler = ApiResponseHandler.for(
+        AuthenticationErrorResponse,
+        (request) => {
+            return authenticateUserAgain();
+        },
+    );
+    const client = new ExampleApiClient(requester, generalResponsesHandler);
+
+
+In order to have multiple  responses to consider, you can clarify them all with the ``handler`` method. Remember that ``ApiResponseHandler`` is an unmutable object, so everytime a
+response is add it will return a new ``ApiResponseHandler`` object. For example:
+
+.. code-block:: javascript
+  :linenos:
+
+    let responsesHandler = new ApiResponseHandler();
+    responsesHandler = responseHandler.handles(
+        SuccessfulApiResponse,
+        (request) => {
+            return doSomething();
+        },
+    );
+    responsesHandler = responseHandler.handles(
+        AuthenticationErrorResponse,
+        (request) => {
+            return authenticateUserAgain();
+        },
+    );
+    const client = new ExampleApiClient(requester, responsesHandler);
+
+Now you may be wondering, what happens if I want to handle a specific response in a different way? Well, you can already do that! every time you indicate
+the way responses should be handled, you are actually overriding the default response handler. So, if you want to handle a specific response in a different way,
+just override the default response handler again.

docs/index.rst

@@ -0,0 +1,22 @@
+.. mdinclude:: ../README.md
+
+Appy-Comm
+-----
+
+Appy-Comm is a library to help you to communicate with Appyx, but also if your are not using it! Now your requests are simpler and responses can be handled easily.
+
+
+.. toctree::
+    :hidden:
+    :maxdepth: 2
+
+    guide
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Developer
+
+   contributing
+   maintaining
+   branding

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd