feat(hook): add useLiquidityPool and useLiquidityPoolActions

[johdanike]

🎯 Summary

Introduces support for Stellar's native AMM liquidity pools by adding the useLiquidityPool and useLiquidityPoolActions hooks. This PR also resolves a foundational type-level bug by formally introducing "liquidity_pool_shares" to the Asset union, allowing the library to accurately track and expose LP balances.

📋 Technical Scope & Changes

• Types & Utils: Added "liquidity_pool_shares" to the Asset union. Removed the as any and as Balance forced casts in parseHorizonBalance along with their lint suppressions.
• Type Guards: Exported isNativeAsset, isIssuedAsset, and a newly created isLiquidityPoolShares guard from the main entry point to allow consumers to narrow the Balance union.
• useBalance Update: Added a third branch to the selector so it can successfully match and return LP positions.
• New Hooks:
  • useLiquidityPool: Fetches reserves, total_shares, fee_bp, and total_trustlines.
  • useLiquidityPoolActions: Implements deposit and withdraw flows.
• Slippage & Safety: deposit strictly requires minPrice and maxPrice, while withdraw strictly requires minAmountA and minAmountB. Omitting these boundaries is rejected (no defaults) to ensure strict slippage protection. No float arithmetic is used for prices/reserves.
• Status: Transaction statuses are derived directly from res.successful.
• Documentation: Added docs/hooks/use-liquidity-pool.md (which notes the useAddTrustline prerequisite) and updated docs/reference/types.md and CHANGELOG.md.
• Tests: Included test coverage using serverMock and adapterMock on the testnet.

✅ Acceptance Criteria

• Asset union includes "liquidity_pool_shares"
• The as any cast and lint suppression at utils/index.ts are gone
• useBalance can select and return an LP share balance
• isNativeAsset, isIssuedAsset, and isLiquidityPoolShares are exported
• useLiquidityPool returns reserves, total shares, and fee
• Deposit and withdraw both implemented and covered by tests with a mocked adapter
• Price bounds and minimum amounts are strictly required
• No float arithmetic on prices or reserves
• The pool-share trustline prerequisite is documented
• status derived from res.successful
• CHANGELOG.md and docs/reference/types.md updated
• Used testnet exclusively in examples and tests
• pnpm test, pnpm lint, pnpm typecheck, and pnpm build all pass locally

Closes #199

[drips-wave]

@johdanike Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits