Refactor client

[skupriienko]

Links:

Jira

Actions:

• Core SDK & Client:

  • Refactor Client to utilize requests.Session for connection pooling, drastically improving performance for sequential requests.
  • Refactor Config into a @dataclass for cleaner configuration state management.

• Decompose Endpoint._build_url and Client.api_call to resolve cyclomatic complexity (C901), extracting _check_dx_guardrails, _build_csv_url, and telemetry extraction into pure @staticmethods.

  • Define explicit public module interfaces using __all__ in __init__.py to prevent namespace pollution.
  • Centralize HTTP status logging within api_call using standard Python logging, and deprecating legacy custom logging handlers.

• Implement Graceful Degradation for legacy kwargs (ensure_ascii, data_encoding) and utility functions (parse_response), wrapping them in standard DeprecationWarnings instead of breaking the API.

• Upgrade the timeout parameter to accept tuple[float, float] and float, increasing the default to 60s to better handle heavy API operations.

• Security & Developer Experience (DX):

  • Mitigate Path Traversal (CWE-22) by strictly applying urllib.parse.quote to dynamically injected id and action_id path parameters.
  • Mitigate Cleartext Transmission (CWE-319) by validating the https scheme and requiring a valid hostname during Config initialization.
  • Prevent HTTP Header/CRLF Injection by explicitly scanning the Bearer token for newline characters before applying it to the session.
  • Add DX Guardrails to emit logger.warning events when detecting ambiguous routing (e.g., using singular /template in Content API v1 or routing Send API outside of v3/v3.1).

• Implement Graceful Degradation for legacy HTTP exceptions (AuthorizationError, ActionDeniedError, etc.), restoring them to preserve 100% backward compatibility for existing try/except blocks.

• Integrate Smart Telemetry to automatically extract Mailjet Trace IDs (CustomID, Campaign, TemplateID) from payloads and inject them into debug logs.

• Unit & Integration Tests:

  • Delete the monolithic test.py and segregate tests into tests/unit/ (offline mocked tests) and tests/integration/ (live network tests).
  • Migrate legacy unittest classes to modern pytest fixtures, refactoring assertions into the AAA (Arrange, Act, Assert) pattern.
  • Implement comprehensive offline mock tests for internal routing, CSV endpoints, and DX guardrail branches.
  • Implement full Template lifecycle integration tests for both Email API (v3) and Content API (v1), ensuring clean teardown via try/finally.
  • Verify real multipart upload behavior for Content API images.
  • Add comprehensive unit tests for legacy deprecations (test_legacy_deprecations.py) and context manager lifecycle.

• CI/CD, Linting & Repository Management:

• Consolidate tooling by migrating completely to Ruff as the single source of truth for formatting and linting, purging legacy tools (Black, Flake8, Pylint, Pydocstyle) from pyproject.toml and environments.

• Update GitHub Actions to utilize pip caching, verify compiled .whl artifacts using twine check, and expand the testing matrix to include Python 3.14.

  • Update .github/dependabot.yml to group minor/patch updates and scan GitHub Actions.
  • Add explicit test-unit and test-integration targets to the Makefile.
  • Align environment-dev.yaml strictly with pyproject.toml and add typing-extensions for robust cross-version type hinting (<3.11).

• Documentation & Samples:

  • Update SECURITY.md to reflect exclusive support for the active branch and forbid reporting CVEs via public issues.
  • Update README.md with new Logging & Debugging guides, updated Python compatibility (3.10-3.14), and modern Content API multipart upload examples.
  • Refresh all files in samples/ to safely fetch credentials using os.environ.get().
  • Update CHANGELOG.md
  • Consolidate legacy smoke tests into an executable samples/smoke_readme_runner.py to dynamically test all README examples.