Add typed response models and fix retrieve_enhanced_track key name bug

[daveronan]

Summary

• Bug fix (key name): retrieve_enhanced_track was using revived_track_tasks_results (snake_case) to read the server response, but the server returns revivedTrackTaskResults (camelCase). This silently broke the primary extraction path, causing the method to always fall through to a slower fallback or fail entirely.
• Bug fix (polling): retrieve_enhanced_track polling exited early on 202 responses because revivedTrackTaskResults was present (with null URLs). Now checks that at least one download URL is populated before treating the task as complete.
• Typed responses: All 7 retrieval methods (retrieve_enhanced_track, retrieve_preview_mix, retrieve_final_mix, retrieve_final_mix_advanced, retrieve_preview_master, retrieve_final_master, analyze_mix) now return typed dataclasses instead of raw dict. New models: EnhancedTrackResult, PreviewMixResult, FinalMixResult, PreviewMasterResult, FinalMasterResult, AnalysisResult.
• Docstring rewrite: Replaced inaccurate/fabricated docstrings across all retrieval methods with accurate field-level documentation matching actual server responses (including the previously undocumented preview_start_time field).
• Examples & tests updated: All example scripts, integration tests, and the smoke test updated from dict .get() access to typed attribute access.

Test plan

• 142 unit tests pass (pytest tests/unit/ -q)
• Smoke test passes against live API (import, enums, health, upload, analysis, enhance preview)
• All 5 runnable examples verified end-to-end against live API:
  • upload_example.py — file uploaded
  • analysis_example.py — full analysis with metrics returned
  • enhance_example.py — preview + full enhancement + 4 stems downloaded
  • mastering_example.py — preview + final master downloaded
  • audio_cleanup_example.py — cleaned audio downloaded
• mix_example.py / advanced_mix_example.py imports verified (require multiple audio files)
• New response dataclasses JSON-serializable via dataclasses.asdict()
• Version bumped to 1.3.2, CHANGELOG updated

---

Note

Medium Risk
Public return types change from dict to dataclasses across multiple controllers, which can break downstream callers and subtly alter fallback parsing behavior.

Overview
Adds typed response models and normalizes retrieval parsing across the SDK. The mix, mastering, enhance, and analysis retrieval methods now return dedicated dataclasses (PreviewMixResult, FinalMixResult, PreviewMasterResult, FinalMasterResult, EnhancedTrackResult, AnalysisResult) instead of raw dicts, and examples/tests were updated to use attribute access (plus asdict() for JSON serialization).

Fixes an enhance retrieval bug and cleans up API response handling/docs. retrieve_enhanced_track now reads the correct server key (revivedTrackTaskResults), polling/parsing logic in several controllers was simplified to extract the expected nested result objects, and docstrings were rewritten to match actual response shapes (including preview_start_time). Version bumped to 1.3.2 with changelog updates.

^{Reviewed by Cursor Bugbot for commit aee61d0. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit aee61d0. Configure here.}

[cursor]

Early return silently drops nested preview mix results

Low Severity

When the API returns previewMixTaskResults with completed data but without a top-level status key, the first condition (line 157) fails because response.get("status") is None. The second condition (line 161) also fails because "status" not in response. The else branch then calls _parse_preview_result(response) on the outer response dict, which only looks for download_url_preview_mixed etc. at the top level — missing the data nested inside previewMixTaskResults. This returns an empty PreviewMixResult and skips polling entirely. The old code returned the raw response dict, which at least preserved the nested data for callers to inspect.

 

^{Reviewed by Cursor Bugbot for commit aee61d0. Configure here.}