Implement `Invoice` model

[codebestia]

The Python Invoice model must be a faithful mirror of the Soroban smart contract struct. There are no line items — the contract models an invoice as a single description + amount + token tuple. All monetary fields (amount, amount_paid, amount_refunded) map to Python Decimal (from i128). All timestamp fields (date_created, date_paid, expires_at) map to Python datetime (converted from u64 Unix timestamps). The id field is the u64 on-chain invoice ID, mapped to Python int.

Proposed Steps:

• Create src/shade/models/invoice.py.
• Define InvoiceStatus as a StrEnum with values: pending, paid, expired, partially_paid, refunded.
• Define Invoice(ShadeObject) with fields: id: int, description: str, amount: Decimal, token: str, status: InvoiceStatus, merchant_id: int, payer: Optional[str], date_created: datetime, date_paid: Optional[datetime], amount_paid: Decimal, amount_refunded: Decimal, expires_at: Optional[datetime].
• Add computed properties: is_paid: bool, is_expired: bool, outstanding: Decimal.
• Write _from_contract_dict(data: dict) classmethod for u64 → int and i128 → Decimal conversions.

Acceptance Criteria:

• Invoice.from_dict(contract_response) populates all fields correctly.
• invoice.amount is a Decimal, not an int or float.
• invoice.date_created is a datetime, not an int.
• invoice.payer is None for an unpaid invoice.
• invoice.is_expired returns True when expires_at is in the past.
• invoice.outstanding equals amount - amount_paid for a partially paid invoice.
• The model has no line_items, customer_email, payment_url, or total fields.

[GBOYEE]

Hello! I'd love to pick this one up. I'd like to take this on (Implement Invoice model). I'll implement it to spec and add tests. I'll open a PR referencing this shortly once assigned.

[sainath5001]

Hi, I would like to work on this issue.

I have experience working with blockchain data structures, smart contract integrations, and strongly typed model implementations. I’m familiar with mapping on-chain data types to application models, handling Decimal conversions for financial values, timestamp conversions, enum-based states, and validation logic.

I can implement the Invoice model with Soroban contract field mapping, status handling, computed properties, and ensure all acceptance criteria are satisfied.

[grantfox-oss]

🦊 GrantFox — @sainath5001 has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #38)
2. Your PR will be reviewed by the ShadeProtocol maintainers

Good luck! Track your progress on GrantFox.

[codebestia]

Hello @sainath5001
What is the update with this task?

[KaruG1999]

Hi, I'm Karen, a developer working with Stellar/Soroban integrations, data modeling, and typed SDK architectures
If this issue is open for contributors, I can take on implementing the Invoice model under src/shade/models/invoice.py. I can start by setting up the InvoiceStatus enum and mapping the Soroban contract types (converting i128 to Python Decimal and u64 Unix timestamps to datetime). I'll implement the computed properties (is_paid, is_expired, outstanding) and the _from_contract_dict deserializer, backed by unit tests covering every conversion and edge case listed in the acceptance criteria