feat: full rewrite with async support, pydantic v2 and modern architecture (#72)

* feat(core): rewrite Capmonster client with Pydantic v2 and modern Python features

- Replaced legacy procedural structure with fully typed class-based design
- Introduced Pydantic v2 models with field validation, serialization, and aliasing
- Implemented sync and async Capmonster clients using httpx
- Added extensible BaseTaskPayload structure with abstract to_request()
- Included validator and field_serializer usage for dynamic task behavior
- Flattened proxy structure via smart task serialization
- Applied frozen and immutable model config where applicable
- Full support for Literal, Optional etc.
- Some test cases prepared with pytest + pytest-asyncio
- Ready for mkdocs documentation generation

BREAKING CHANGE: API usage has completely changed from v3.2 to v4.0. All task creation methods now rely on structured payloads and typed clients.

* build: migrate to PEP 621-compatible pyproject.toml and restructure project

- Replaced setup.py and setup.cfg with pyproject.toml for a modern build system. Updated project structure to align with the src directory convention. Adjusted imports, examples, and documentation for the updated layout and dependency changes.

* docs: remove old markdown and add structured API documentation

Removed outdated CODE-OF-CONDUCT.md and README.md files. Introduced a detailed, structured API reference and examples using MkDocs format. Includes documentation for tasks, exceptions, error codes, and usage examples in both synchronous and asynchronous modes.

* chore: remove outdated examples and improve the project structure

* ci: add new tests and CI setup for capmonster tasks

Author: alperensert

.editorconfig

@@ -0,0 +1,6 @@
+# .editorconfig
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true

.github/ISSUE_TEMPLATE/bug_report.md

@@ -10,25 +10,20 @@ assignees: alperensert
 **Describe the bug**
 A clear and concise description of what the bug is.
 
-**To Reproduce**
-Steps to reproduce the behavior:
-1. Go to '...'
-2. Click on '....'
-3. Scroll down to '....'
-4. See error
-
 **Expected behavior**
 A clear and concise description of what you expected to happen.
 
 **Screenshots**
 If applicable, add screenshots to help explain your problem.
 
 **Desktop (please complete the following information):**
- - OS: [e.g. iOS]
- - Browser [e.g. chrome, safari]
- - Version [e.g. 22]
+
+- OS: [e.g. iOS]
+- Browser [e.g. chrome, safari]
+- Version [e.g. 22]
 
 **Simplified error traceback (if you have)**
+
 - Directory: [e.g main]
 - File: [e.g recaptcha_v2.py]
 - Line(s): [e.g 30, 66, 82]

.github/ISSUE_TEMPLATE/help-wanted.md

@@ -8,13 +8,15 @@ assignees: ''
 ---
 
 **Your purpose**
-Are you trying to pass a web site protection or can't find the required keys? Can't submit the captcha? Or something else.. Please explain it in here.
+Are you trying to pass website protection or can't find the required keys? Can't submit the captcha? Or something else.
+Please explain it in here.
 
 **Highly required informations**
-- Web site url (where placed the captcha)
+
+- Website url (where placed the captcha)
 
 **Things you've tried**
 The followed way to solve your problem. Explain it briefly, like I changed ... to ... but it doesn't worked
 
-**Do not forget**
-90% of help requests was about submitting captcha in web sites. In this cases, please take a look at to **examples**
+**Remember**
+90% of help requests were about submitting captcha in websites. In this case, please take a look at to **docs**.

.github/dependabot.yml

@@ -1,12 +1,6 @@
 version: 2
 updates:
   - package-ecosystem: "pip"
-    directory: "/capmonster_python"
-    schedule:
-      interval: "daily"
-  - package-ecosystem: "npm"
-    directory: "/docs"
+    directory: "/src/capmonster_python"
     schedule:
       interval: "weekly"
-    ignore:
-      - dependency-name: "*"

.github/workflows/ghpages.yml

@@ -1,14 +1,14 @@
-name: Deploy Gatsby Documentation to Pages
+name: Deploy MkDocs to GitHub Pages
 
 on:
   push:
-    branches: ["master"]
+    branches: [ "master" ]
     paths:
       - docs/**
   workflow_dispatch:
 
 permissions:
-  contents: read
+  contents: write
   pages: write
   id-token: write
 
@@ -22,67 +22,22 @@ defaults:
     working-directory: docs
 
 jobs:
-  build:
+  deploy:
     runs-on: ubuntu-latest
+
     steps:
-      - name: Checkout
+      - name: Checkout repository
         uses: actions/checkout@v3
-      - name: Detect package manager
-        id: detect-package-manager
-        run: |
-          if [ -f "yarn.lock" ]; then
-            echo "manager=yarn" >> $GITHUB_OUTPUT
-            echo "command=install" >> $GITHUB_OUTPUT
-            echo "file=**/yarn.lock" >> $GITHUB_OUTPUT
-            exit 0
-          elif [ -f "package.json" ]; then
-            echo "manager=npm" >> $GITHUB_OUTPUT
-            echo "command=ci" >> $GITHUB_OUTPUT
-            echo "file=**/package.json" >> $GITHUB_OUTPUT
-            exit 0
-          else
-            echo "Unable to determine packager manager"
-            exit 1
-          fi
-      - name: Setup Node
-        uses: actions/setup-node@v3
-        with:
-          node-version: "18"
-          cache: ${{ steps.detect-package-manager.outputs.manager }}
-          cache-dependency-path: ${{ steps.detect-package-manager.outputs.file }}
-        
-      - name: Setup Pages
-        id: pages
-        uses: actions/configure-pages@v2
-        with:
-          static_site_generator: gatsby
-      - name: Restore cache
-        uses: actions/cache@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
         with:
-          path: |
-            public
-            .cache
-          key: ${{ runner.os }}-gatsby-build-${{ hashFiles('public') }}
-          restore-keys: |
-            ${{ runner.os }}-gatsby-build-
+          python-version: '3.10'
+
       - name: Install dependencies
-        run: ${{ steps.detect-package-manager.outputs.manager }} ${{ steps.detect-package-manager.outputs.command }}
-      - name: Build with Gatsby
-        env:
-          PREFIX_PATHS: 'true'
-        run: ${{ steps.detect-package-manager.outputs.manager }} run build
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v1
-        with:
-          path: ./docs/public
+        run: |
+          pip install mkdocs mkdocs-material mkdocstrings[python]
 
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v1
+      - name: Build and deploy
+        run: |
+          mkdocs gh-deploy --force

.github/workflows/publish.yml

@@ -2,38 +2,37 @@ name: Publish Python Package 🐍
 
 on:
   release:
-    types: [published]
+    types: [ published ]
 
 jobs:
   deploy:
-
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
-    - name: Set up Python
-      uses: actions/setup-python@v3
-      with:
-        python-version: "3.9"
-
-    - name: Install setup dependencies
-      run: make setup_dependencies
-
-    - name: Install dependencies
-      run: make build
-
-    - name: Build package
-      run: python -m build
-
-    - name: Publish package to TestPYPI
-      uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
-      with:
-        user: __token__
-        password: ${{ secrets.TEST_PYPI_TOKEN }}
-        repository_url: https://test.pypi.org/legacy/
-
-    - name: Publish package to PYPI
-      uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
-      with:
-        user: __token__
-        password: ${{ secrets.PYPI_TOKEN }}
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v3
+        with:
+          python-version: "3.10"
+
+      - name: Install setup dependencies
+        run: make setup_dependencies
+
+      - name: Install dependencies
+        run: make build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish package to TestPYPI
+        uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
+        with:
+          user: __token__
+          password: ${{ secrets.TEST_PYPI_TOKEN }}
+          repository_url: https://test.pypi.org/legacy/
+
+      - name: Publish package to PYPI
+        uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_TOKEN }}

.github/workflows/tests.yml

@@ -0,0 +1,37 @@
+name: Run Pytest Tests
+
+on:
+  push:
+    branches: [ "master" ]
+    paths:
+      - "tests/**"
+      - ".github/workflows/test.yml"
+      - "**.py"
+  pull_request:
+    branches: [ "master" ]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    env:
+      API_KEY: ${{ secrets.API_KEY }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+
+      - name: Install dependencies
+        run: |
+          pip install -r requirements.txt
+          pip install pytest
+
+      - name: Run tests
+        run: |
+          pytest tests/

.gitignore

@@ -3,4 +3,7 @@
 **/.cache
 **/node_modules
 **/.DS_Store
-**/.venv
+**/.venv
+**/site
+**/dist
+**/*.egg-info

CODE-OF-CONDUCT.md

@@ -11,8 +11,5 @@ install_pkg:
 	python -m pip install --upgrade pip wheel
 	pip install .
 
-test:
-	python -m unittest -v tests/test_tasks.py
-
 setup_dependencies:
 	pip install setuptools_scm wheel