[FEATURE] Add backward compatibility shims for v0.x projects migrating to v1.

[thewebscraping]

Summary

I recently upgraded the payos SDK from version 0.1.x (specifically 0.1.8) to the latest v1.0.1. While I appreciate the massive improvements in v1 (async support, cleaner architecture, and Pydantic models), the migration was quite "painful" as it caused an immediate production outage (500 Internal Server Error) due to several removed modules.

Problem/Use Case

Many automated tools (like pip install --upgrade or uv sync --upgrade) update packages without the developer checking the GitHub release notes first. In v1.0.0, the removal of core modules led to immediate ModuleNotFoundError:

• payos.constants (e.g., PAYOS_BASE_URL, ERROR_CODE) is gone.
• payos.custom_error (PayOSError) is gone.
• Essential methods like .to_json() on result types were removed.

Even though there is a MIGRATION.md, the lack of a Compatibility Layer means any existing project will break instantly upon upgrade, without a chance to see a DeprecationWarning.

Proposed Solution

To improve the Developer Experience (DX) and provide a smoother transition, I suggest adding temporary "shims" or aliases for at least one or two minor versions:

• Module Aliases: Re-add payos/constants.py and payos/custom_error.py as shells that import from the new locations (e.g., _core/exceptions.py) and trigger a DeprecationWarning.
• Method Fallbacks: Temporarily keep methods like to_json() or to_dict() on models, pointing to the new .model_dump() logic, with a warning.
• Prevents Downtime: Existing apps won't crash immediately. Developers will see warnings in their logs and have time to refactor.
• Professionalism: Major SDKs (like Stripe, Twilio) usually provide a migration path via aliases before fully pruning old code.
• Support: It reduces the number of support requests from users confused by ModuleNotFoundError.

Alternative Solutions

No response

Additional Context

No response

Thank you for the hard work on this SDK!
Best regards,
Tu Pham

[locbt-casso]

Thank you for reporting this. Support for backward compatibility with the v0 SDK is currently being implemented and will be included in the upcoming 1.1.x release. The primary reason this wasn’t supported earlier is that v0 was an unstable version, and we decided to focus on a full SDK rewrite before releasing v1 to ensure a more solid foundation. Appreciate your patience and the report.