Add opt-in verbose mode for capturing HTTP response metadata

[omercnet]

Summary

Add verbose mode to DescopeClient and HTTPClient to capture HTTP response metadata (headers, status codes, etc.) for debugging failed requests with Descope support.

Key Changes

• DescopeResponse wrapper class: Provides dict-like interface while exposing HTTP metadata (headers, status_code, text, etc.)
• Verbose parameter: Added to DescopeClient and HTTPClient (defaults to False for backward compatibility)
• get_last_response() methods: Access captured response data for debugging
• Full backward compatibility: Zero overhead when disabled (default behavior unchanged)
• Comprehensive testing: All 366 tests passing
• Documentation & examples: Added usage examples and README documentation
• Pre-commit hooks: Updated to use official poetry-plugin-export hook

Use Case

This enables customers to capture cf-ray headers and other HTTP metadata when troubleshooting issues with Descope support:

client = DescopeClient(project_id, management_key, verbose=True)
try:
    client.mgmt.user.create(login_id="test@example.com")
except AuthException:
    resp = client.get_last_response()
    if resp:
        print(f"cf-ray: {resp.headers.get('cf-ray')}")  # For support tickets
        print(f"Status: {resp.status_code}")

Testing

• ✅ All 366 tests passing
• ✅ Added 13 new tests for verbose mode functionality
• ✅ Backward compatibility verified (default behavior unchanged)
• ✅ Pre-commit hooks passing

Files Changed

• descope/http_client.py - Core implementation (DescopeResponse class, verbose mode)
• descope/descope_client.py - Client-level verbose mode support
• descope/__init__.py - Export DescopeResponse
• tests/test_http_client.py - Unit tests for DescopeResponse and HTTPClient verbose mode
• tests/test_descope_client.py - Integration tests for DescopeClient verbose mode
• samples/verbose_mode_example.py - Usage examples (new file)
• README.md - Documentation added
• .pre-commit-config.yaml - Updated to use official poetry-plugin-export hook

Fixes https://github.com/descope/etc/issues/12957

[Copilot]

Pull request overview

This PR adds an opt-in verbose mode to capture HTTP response metadata (headers, status codes, etc.) for debugging failed requests with Descope support. The implementation introduces a DescopeResponse wrapper class that maintains backward compatibility while exposing HTTP metadata, and adds verbose parameters to both DescopeClient and HTTPClient that default to False.

Key Changes:

• New DescopeResponse wrapper providing dict-like interface plus HTTP metadata access
• Opt-in verbose parameter added to client constructors (defaults to False)
• Response capture logic in HTTP methods when verbose mode is enabled

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
descope/http_client.py	Core implementation with DescopeResponse class and verbose mode capture logic
descope/descope_client.py	Added verbose parameter forwarding and get_last_response() method
descope/__init__.py	Exported DescopeResponse for public API access
tests/test_http_client.py	Unit tests for DescopeResponse wrapper and HTTPClient verbose mode
tests/test_descope_client.py	Integration tests for DescopeClient verbose mode functionality
samples/verbose_mode_example.py	Example demonstrating verbose mode usage for debugging
README.md	Documentation for verbose mode feature and usage examples
.pre-commit-config.yaml	Updated pre-commit hook versions and reorganized poetry-export hook

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

Coverage report

The coverage rate went from 98.14% to 98.22% ⬆️

100% of new lines are covered.

Diff Coverage details (click to unfold)

descope/http_client.py

100% of new lines are covered (100% of the complete file).

descope/descope_client.py

100% of new lines are covered (97.89% of the complete file).

descope/init.py

100% of new lines are covered (100% of the complete file).

[dorsha]

Coverage report

The coverage rate went from 98.14% to 97.72% ⬇️

83.75% of new lines are covered.

Diff Coverage details (click to unfold)

@omercnet check the coverage issue

[omercnet]

Coverage report

The coverage rate went from 98.14% to 97.72% ⬇️

83.75% of new lines are covered.

Diff Coverage details (click to unfold)

@omercnet check the coverage issue

Fixed

[dorsha]

Looks good to me.
@ruvenzx please test this and approve.