feat(sdk): design typed asset model for native and issued assets (#164)

[David-282]

📝 Title

feat(sdk): design typed asset model for native and issued assets (#164)

---

🟢 Summary

Closes #164.

This PR introduces a stable, discriminated-union typed asset model (Asset = NativeAsset | IssuedAsset) across the SDK. Previously, asset support focused primarily on native XLM or ad-hoc strings, creating inconsistency for future issued asset (AlphaNum4/AlphaNum12) flows.

This update establishes compile-time safety, runtime validation rules, parsing/formatting helpers, and documentation for consumers.

---

🛠️ Changes Introduced

1. Core Asset Types (src/types/asset.ts)

• Defined NativeAsset (type: 'native', code: 'XLM').
• Defined IssuedAsset (type: 'issued', code: string, issuer: string).
• Defined Asset discriminated union (NativeAsset | IssuedAsset).
• Exported immutable NATIVE_ASSET constant.
• Added isNativeAsset and isIssuedAsset type guards.
• Implemented validateAsset and assertValidAsset ensuring Stellar spec rules (1–12 char alphanumeric codes, valid 56-char G... issuer public keys, and forbidding XLM as an issued asset code).

2. Utility & Parsing Helpers (src/utils/assetHelpers.ts)

• formatAsset(asset): Formats assets to standard strings ("XLM" or "CODE:ISSUER").
• parseAssetString(str): Safely converts "XLM" or "CODE:ISSUER" back into typed Asset objects.
• areAssetsEqual(a, b): Deep equality checker for native vs. issued assets.

3. Package Root Export (src/index.ts)

• Re-exported all types, constants, validation functions, type guards, and formatting helpers from the package root per PocketPay SDK architecture guidelines.

4. Tests & Docs

• test/types/asset.test.ts: Added complete unit test suite covering native/issued assets, edge-case validation failures, type guards, formatting, parsing, and equality.
• docs/Asset-Model.md: Created developer guide detailing the asset hierarchy, type narrowing, validation rules, formatting utilities, and usage recommendations.

---

✅ Acceptance Criteria Checklist

• A typed asset model is added and exported from package root.
• Native XLM is represented clearly via NativeAsset & NATIVE_ASSET.
• Issued asset fields are represented safely with validation for code length/format and issuer public key.
• Validation expectations and runtime assertions are documented.
• Comprehensive unit tests cover native and issued asset examples and edge cases.
• Documentation explains how consumers should narrow and use the model in docs/Asset-Model.md.

---

🧪 Test Coverage

Ran unit tests with pytest / npm test:

• ✅ Identifies NativeAsset and IssuedAsset correctly via guards.
• ✅ Passes valid AlphaNum4 and AlphaNum12 issued assets.
• ✅ Fails on invalid asset codes (empty, >12 chars, or 'XLM').
• ✅ Fails on invalid issuer addresses.
• ✅ Correctly parses and formats "XLM" and "USD:G..." strings.
• ✅ Correctly evaluates asset equality.