Enhance README, refactor package, and improve testing setup

.convcommit

@@ -0,0 +1,76 @@
+# convcommit - Conventional Commit message builder
+# This file is read by the `convcommit` CLI tool to populate
+# the interactive selector menus.
+# Commit this file to share the project's commit vocabulary with the team.
+#
+# FORMAT
+#   type:<value>      — commit type option (e.g. fix, feat, docs)
+#   scope:<value>     — commit scope option
+#   message:<value>   — commit message template
+#
+# SPECIAL PREFIXES
+#   ~<value>          — marks the default selection
+#   _                 — enables free-text manual input (press ".")
+#   [X]<value>        — forces key letter X for this entry (e.g. [B]build, [W]wip)
+#
+# HOW TO USE (interactive)
+#   Run `convcommit` in a git repo. A menu appears for type, scope, message.
+#   Press the letter in brackets [A][B]... or [.] for free-text input.
+#   Stage and push in one shot:
+#     convcommit -a -p
+#
+# HOW TO USE (direct flags — scripts, AI agents)
+#   Bypass the selector entirely with explicit flags:
+#     convcommit --type fix --scope auth --message "fix null pointer" --push
+#     convcommit -t feat -s api -m "add endpoint" -a -p
+#
+# SMART PATTERN — stage specific files and commit in one command
+#   Use --add instead of nested command substitution.
+#   Anti-pattern (avoid):
+#     msg=$(convcommit --type fix --message "fix") && git commit -m "$msg" && git push
+#   Recommended:
+#     convcommit --add src/auth.sh --type fix --scope auth --message "fix null pointer" --push
+#   Stage multiple files:
+#     convcommit --add src/auth.sh --add tests/auth_test.sh -t test -s auth -m "add tests" -p
+#
+# HOW TO USE (pipe / non-interactive)
+#   Pipe selections as lines: one per stage (type, scope, message).
+#   Use the letter shown in the menu, or "." to trigger free-text input.
+#   Examples:
+#     printf "G\n.\nfix null pointer in login\n" | convcommit
+#     printf "F\n\nadd endpoint\n" | convcommit -a -p
+#   Capture just the formatted message:
+#     msg=$(printf "G\n\nfix null pointer\n" | convcommit)
+#
+# OTHER USEFUL FLAGS
+#   --reset   Regenerate this file with the latest defaults
+#   --help    Show all options
+#
+# INSTALLATION
+#   convcommit is a single bash file with no dependencies.
+#   Install it locally in your project:
+#     curl -fsSL https://raw.githubusercontent.com/francescobianco/convcommit/refs/heads/main/bin/convcommit \
+#       -o bin/convcommit && chmod +x bin/convcommit
+#   Or system-wide:
+#     curl -fsSL https://raw.githubusercontent.com/francescobianco/convcommit/refs/heads/main/bin/convcommit \
+#       -o /usr/local/bin/convcommit && chmod +x /usr/local/bin/convcommit
+type:[B]build
+type:~chore
+type:[D]docs
+type:deps
+type:feat
+type:fix
+type:ci
+type:init
+type:merge
+type:perf
+type:refactor
+type:revert
+type:security
+type:style
+type:test
+type:[W]wip
+scope:_
+scope:~
+message:_
+message:~_

.github/workflows/python.yml

@@ -0,0 +1,37 @@
+name: Python
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [ "3.10", "3.11", "3.12" ]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+        with:
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+
+      - name: Install dependencies
+        run: poetry install --no-interaction
+
+      - name: Test
+        run: poetry run pytest
+
+      - name: Build
+        run: poetry build

.gitignore

@@ -1,3 +1,7 @@
+# IDEs and editors
+.idea/
+.vscode/
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -26,6 +30,7 @@ share/python-wheels/
 *.egg
 MANIFEST
 
+
 # PyInstaller
 #  Usually these files are written by a python script from a template
 #  before PyInstaller builds the exe, so as to inject date/other infos into it.

Makefile

@@ -0,0 +1,72 @@
+#!make
+
+# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+#                                                                             #
+#      ____                               _                                   #
+#     / __ \____  ___  ____  ____ _____  (_) ®                                #
+#    / / / / __ \/ _ \/ __ \/ __ `/ __ \/ /                                   #
+#   / /_/ / /_/ /  __/ / / / /_/ / /_/ / /                                    #
+#   \____/ .___/\___/_/ /_/\__,_/ .___/_/                                     #
+#       /_/                    /_/                                            #
+#                                                                             #
+#   The Largest Certified API Marketplace                                     #
+#   Accelerate Digital Transformation • Simplify Processes • Lead Industry    #
+#                                                                             #
+#   ═══════════════════════════════════════════════════════════════════════   #
+#                                                                             #
+#   Project:        openapi-python-sdk                                        #
+#   Author:         Michael Cuffaro (@maiku1008)                              #
+#   Copyright:      (c) 2025 Openapi®. All rights reserved.                   #
+#   License:        MIT                                                       #
+#   Maintainer:     Francesco Bianco                                          #
+#   Contact:        https://openapi.com/                                      #
+#   Repository:     https://github.com/openapi-it/openapi-python-sdk/         #
+#   Documentation:  https://console.openapi.com/                              #
+#                                                                             #
+#   ═══════════════════════════════════════════════════════════════════════   #
+#                                                                             #
+#   "Truth lies at the source of the stream."                                 #
+#                                  — English Proverb                          #
+#                                                                             #
+# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
+
+## =========
+## Variables
+## =========
+
+export PATH := $(HOME)/.local/bin:$(PATH)
+VERSION := $(shell grep '^version' pyproject.toml | head -1 | sed 's/.*"\(.*\)".*/\1/')
+
+## ====================
+## Development Commands
+## ====================
+
+dev-push:
+	@git config credential.helper 'cache --timeout=3600'
+	@git add .
+	@git commit -m "$$(read -p 'Commit message: ' msg; echo $$msg)" || true
+	@git push
+
+## ================
+## Release Commands
+## ================
+
+.PHONY: setup build publish release
+
+setup:
+	@poetry --version > /dev/null 2>&1 || \
+		(echo "Installing Poetry..." && curl -sSL https://install.python-poetry.org | python3 -)
+
+build: setup
+	@echo "Building version $(VERSION)..."
+	@poetry build
+
+publish: build
+	@echo "Publishing version $(VERSION) to PyPI..."
+	@poetry publish
+
+release: publish
+	@echo "Tagging release $(VERSION)..."
+	@git tag -fa "$(VERSION)" -m "Release $(VERSION)"
+	@git push origin --tags -f
+	@echo "Released $(VERSION) successfully."