feat(models): implement Transfer model and TransferStatus enum

[angelraph]

Description

Implements the Transfer model as specced in #40: represents a payout of funds from the merchant wallet to a destination address, following the same pydantic ShadeObject pattern established by Merchant (camelCase API fields aliased to snake_case, extra="allow" for forward compatibility, pydantic.ValidationError wrapped into InvalidRequestError).

• src/shade/models/transfer.py: Transfer model with id, source_address, destination_address, amount: Decimal, asset: str, status: TransferStatus, stellar_tx_hash: Optional[str], fee: Optional[Decimal], created_at: datetime.
• TransferStatus enum: pending, processing, completed, failed.
• asset defaults to "XLM" both when the key is absent and when the API sends an explicit null.
• source_address / destination_address are validated as Stellar ed25519 public keys, matching Merchant.address.
• Exported from shade.models and the top-level shade package.

Fixes #40

Type of change

• New feature (non-breaking change which adds functionality)

How Has This Been Tested?

• Added tests/test_transfer.py covering all three acceptance criteria plus edge cases (missing asset/fee, null asset, invalid status, invalid addresses, non-positive amount, negative fee, missing id, unknown-field passthrough, dict round-trip).
• pytest -q — 196 passed, 3 skipped (full existing suite + 17 new tests).
• flake8 src tests --select=E9,F63,F7,F82 — clean.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• My changes generate no new warnings
• I have added tests that prove my feature works
• New and existing unit tests pass locally with my changes

Summary by CodeRabbit

• New Features
  • Added support for representing merchant wallet transfers and their lifecycle statuses.
  • Transfer details now include source and destination addresses, amount, asset, fees, transaction hash, and creation time.
  • Added validation for Stellar addresses, positive amounts, and non-negative fees.
  • Transfer data supports automatic field mapping, decimal conversion, and an XLM default asset.

[coderabbitai]

Warning

Review limit reached

@angelraph, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 49 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 3e0d499e-9414-4d74-9469-abb0998df49e

📥 Commits

Reviewing files that changed from the base of the PR and between fca00e2 and fe6635b.

📒 Files selected for processing (2)

• src/shade/models/transfer.py
• tests/test_transfer.py

📝 Walkthrough

Walkthrough

Changes

Transfer model

Layer / File(s)	Summary
Transfer contract and exports src/shade/models/transfer.py, src/shade/models/__init__.py, src/shade/__init__.py	Adds TransferStatus, the aliased Transfer model, validation rules, and top-level package exports.
Validation and round-trip coverage tests/test_transfer.py	Tests parsing, defaults, enum conversion, validation errors, exported symbols, unknown-key preservation, and camelCase serialization round-trips.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant APIResponse
  participant Transfer.from_dict
  participant PydanticValidators
  APIResponse->>Transfer.from_dict: camelCase transfer payload
  Transfer.from_dict->>PydanticValidators: mapped model fields
  PydanticValidators-->>Transfer.from_dict: validated Transfer instance

Loading

Possibly related PRs

• ShadeProtocol/shade-python#44: Adds another model and status enum to the shared model exports.
• ShadeProtocol/shade-python#45: Updates the same package export surfaces for a new model.

Suggested reviewers: giftexceed

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding the Transfer model and TransferStatus enum.
Description check	✅ Passed	The description includes the summary, issue reference, type of change, and testing details, matching the template well.
Linked Issues check	✅ Passed	The PR implements the Transfer model, fields, enum, and from_dict behavior required by issue #40.
Out of Scope Changes check	✅ Passed	The changes stay within the Transfer model scope, with exports and tests supporting the requested feature.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/shade/models/transfer.py`:
- Around line 50-55: The _default_asset validator currently converts malformed
falsy values such as False and 0 to XLM. Update its fallback condition to apply
only when value is None or an empty string, while preserving valid non-empty
asset strings unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 67522adc-46ce-4f08-85ca-cef358f4e0f6

📥 Commits

Reviewing files that changed from the base of the PR and between 475b970 and fca00e2.

📒 Files selected for processing (4)

• src/shade/__init__.py
• src/shade/models/__init__.py
• src/shade/models/transfer.py
• tests/test_transfer.py

[codebestia]

LGTM!
Nice Implementation.
Thank you for your contribution.