feat(models): add AssetBalance and Balance models for per-asset balan…

[Yourbigmike]

Closes #43
breakdown

• AssetBalance: asset_code, asset_issuer (optional), balance (Decimal)
• Balance: id, merchant_id, balances list with get() helper
• get() returns None for missing assets instead of raising
• Case-insensitive lookup, camelCase alias support
• 20 new tests, all 220 tests passing

Description

Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change.

Fixes # (issue)

Type of change

Please delete options that are not relevant.

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration

• Test A
• Test B

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Summary by CodeRabbit

• New Features

  • Added public balance models for merchant wallets and individual assets.
  • Balance details include asset codes, issuers, and precise decimal amounts.
  • Added case-insensitive asset lookup, returning matching balances when available.
  • Exposed the new balance models through the package’s public interface.

• Tests

  • Added coverage for balance parsing, serialization, lookups, defaults, and data handling.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds AssetBalance and Balance models for merchant wallet balances, exports them from shade.models and shade, and adds tests for parsing, serialization, lookup behavior, defaults, representations, and public exports.

Changes

Balance models and validation

Layer / File(s)	Summary
Balance model contract and public exports src/shade/models/balance.py, src/shade/models/__init__.py, src/shade/__init__.py	Defines asset and merchant balance models with API field aliases, Decimal balances, case-insensitive asset lookup, and package-level exports.
Balance parsing and behavior validation tests/test_balance.py	Tests payload conversion, nested model construction, serialization round trips, unknown-key preservation, lookup behavior, defaults, representations, and exports.

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

Possibly related issues

• Implement Balance model #43 — The PR implements the proposed AssetBalance and Balance models, including the get() helper and exports.

Suggested reviewers: giftexceed

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description summarizes the change and testing, but it leaves required template sections like motivation, dependencies, type of change, and checklist largely unfilled.	Add a filled summary with motivation/context, the fixed issue, dependencies if any, selected change type, testing details, and complete the checklist.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly matches the main change: adding new balance models under models.

✨ 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]

🧹 Nitpick comments (1)

src/shade/models/balance.py (1)

45-45: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Use a default_factory for balances.

This makes the per-instance list default explicit and avoids RUF012.

Proposed fix

-    balances: List[AssetBalance] = []
+    balances: list[AssetBalance] = Field(default_factory=list)

🤖 Prompt for 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.

In `@src/shade/models/balance.py` at line 45, Update the balances field
declaration in the model to use the dataclass field default_factory with a list
factory instead of assigning a mutable list directly. Preserve the
List[AssetBalance] type and ensure each model instance receives its own empty
list.

Source: Linters/SAST tools

🤖 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.

Nitpick comments:
In `@src/shade/models/balance.py`:
- Line 45: Update the balances field declaration in the model to use the
dataclass field default_factory with a list factory instead of assigning a
mutable list directly. Preserve the List[AssetBalance] type and ensure each
model instance receives its own empty list.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 32424ee6-c892-4a67-aadc-347e150c535c

📥 Commits

Reviewing files that changed from the base of the PR and between 264d02d and 0a50f8d.

📒 Files selected for processing (4)

• src/shade/__init__.py
• src/shade/models/__init__.py
• src/shade/models/balance.py
• tests/test_balance.py

[codebestia]

LGTM!
Nice Implementation.
Thank you for your contribution.