Add documentation in README

CONTRIBUTE.md

@@ -0,0 +1,25 @@
+## Development
+
+Some development notes
+
+### Coding style guidelines
+
+The configurations in [.editorconfig](./.editorconfig) and some in [pyproject.toml](./pyptoject.toml) are put in place in order to format and check compliance with [PEP 8](https://pep8.org) (with some exceptions).
+
+[.pre-commit-config.yaml](./.pre-commit-config.yaml) defines a set of hooks to be executed right before each commit so that [ruff](https://docs.astral.sh/ruff/) (a blazingly fast linter and formatter) is called on the changes made.
+
+This project uses [`uv`](https://docs.astral.sh/uv/) as package and project manager. To set it up:
+
+1. Create a virtual environment and install the packages:
+    ```shell
+    uv sync
+    ```
+2. Install the hooks running:
+    ```shell
+    uvx pre-commit install
+    ```
+3. Now on every `git commit` the `pre-commit` hook (inside `.git/hooks/`) will be run.
+
+#### Configuring your editor
+
+To configure your code editor [read `ruff`'s documentation about it](https://docs.astral.sh/ruff/editors/).

README.md

@@ -2,28 +2,58 @@
 
 SDK to communicate with Virtual Queue's API in Python projects.
 
-## Development
-
-Some development notes
-
-### Coding style guidelines
-
-The configurations in [.editorconfig](./.editorconfig) and some in [pyproject.toml](./pyptoject.toml) are put in place in order to format and check compliance with [PEP 8](https://pep8.org) (with some exceptions).
-
-[.pre-commit-config.yaml](./.pre-commit-config.yaml) defines a set of hooks to be executed right before each commit so that [ruff](https://docs.astral.sh/ruff/) (a blazingly fast linter and formatter) is called on the changes made.
-
-This project uses [`uv`](https://docs.astral.sh/uv/) as package and project manager. To set it up:
-
-1. Create a virtual environment and install the packages:
-    ```shell
-    uv sync
-    ```
-2. Install the hooks running:
-    ```shell
-    uvx pre-commit install
-    ```
-3. Now on every `git commit` the `pre-commit` hook (inside `.git/hooks/`) will be run.
-
-#### Configuring your editor
-
-To configure your code editor [read `ruff`'s documentation about it](https://docs.astral.sh/ruff/editors/).
+## How to use
+
+> [!NOTE]
+> See [`examples/`](./examples/) for more
+
+You can verify the token with `TokenVerifier` like this:
+
+```python
+from vqueue import TokenVerifier
+from vqueue.exceptions import VQueueApiError, VQueueError, VQueueNetworkError
+
+
+def your_function_or_handler():
+    # Get the token from the request in your system
+    token = str(uuid4())  # This is an example UUIDv4
+
+    # This handles the connections with a session and can be reused
+    # for better performance
+    verifier = TokenVerifier()
+
+    try:
+        # Handle the happy path
+        verified_result = verifier.verify_token(token)
+        print("The token was successfuly verified:", verified_result)
+    except ValueError as ve:
+        # Then handle the possible errors
+        # Of course, you should handle the exceptions with more grace than this
+        print("The token is not valir UUID", ve)
+    except VQueueNetworkError as ne:
+        print("Network error", ne)
+    except VQueueApiError as ae:
+        print("The API returned an error status", ae)
+    except VQueueError as vqe:
+        print("A generic error with the Virtual Queue system or this SDK", vqe)
+```
+
+You can also wrap your code in a context managed `with` block:
+
+```python
+    with TokenVerifier() as verfifier:
+        try:
+            # Handle the happy path
+            verified_result = verifier.verify_token(token)
+            print("The token was successfuly verified:", verified_result)
+        except ValueError as ve:
+            # Then handle the possible errors
+            # Of course, you should handle the exceptions with more grace than this
+            print("The token is not valir UUID", ve)
+        except VQueueNetworkError as ne:
+            print("Network error", ne)
+        except VQueueApiError as ae:
+            print("The API returned an error status", ae)
+        except VQueueError as vqe:
+            print("A generic error with the Virtual Queue system or this SDK", vqe)
+```

examples/verify-token.py

@@ -0,0 +1,32 @@
+from uuid import uuid4
+
+from vqueue import TokenVerifier
+from vqueue.exceptions import VQueueApiError, VQueueError, VQueueNetworkError
+
+
+def your_function_or_handler():
+    # Get the token from the request in your system
+    token = str(uuid4())  # This is an example UUIDv4
+
+    # This handles the connections with a session and can be reused
+    # for better performance
+    verifier = TokenVerifier()
+
+    try:
+        # Handle the happy path
+        verified_result = verifier.verify_token(token)
+        print("The token was successfuly verified:", verified_result)
+    except ValueError as ve:
+        # Then handle the possible errors
+        # Of course, you should handle the exceptions with more grace than this
+        print("The token is not valir UUID", ve)
+    except VQueueNetworkError as ne:
+        print("Network error", ne)
+    except VQueueApiError as ae:
+        print("The API returned an error status", ae)
+    except VQueueError as vqe:
+        print("A generic error with the Virtual Queue system or this SDK", vqe)
+
+
+if __name__ == "__main__":
+    your_function_or_handler()

src/vqueue/queues.py

@@ -1,4 +1,4 @@
-from pathlib import Path
+from urllib.parse import urljoin
 
 import requests
 
@@ -7,8 +7,8 @@
 from .types import VerificationResult, VerificationResultData
 from .utils import validate_uuidv4
 
-QUEUES_API_URL = Path(API_BASE_PATH).joinpath("queue/")
-VERIFY_API_URL = QUEUES_API_URL.joinpath("verify")
+QUEUES_API_URL = urljoin(API_BASE_PATH, "queue/")
+VERIFY_API_URL = urljoin(QUEUES_API_URL, "verify")
 
 
 class TokenVerifier:
@@ -75,7 +75,7 @@ def verify_token(self, token: str) -> VerificationResult:
 
         raise VQueueApiError(
             response.status_code,
-            response_data["message"],
-            response_data["error_code"],
-            response_data["data"],
+            response_data.get("message"),
+            response_data.get("error_code"),
+            response_data.get("data"),
         )