From 1f1ee2f67b0481f0cbc5f9ca77354e2ab10c0c0e Mon Sep 17 00:00:00 2001 From: zp6 Date: Fri, 15 May 2026 00:21:06 +0800 Subject: [PATCH] feat: enhance docs for GitHub Pages deployment - Add docs/guide/usage.md with comprehensive React hooks and CLI usage - Update docs/api/index.md with complete API overview - Update VitePress sidebar to include Usage guide Part of #21 --- docs/.vitepress/config.mjs | 1 + docs/api/index.md | 59 +++++++--- docs/guide/usage.md | 219 +++++++++++++++++++++++++++++++++++++ 3 files changed, 265 insertions(+), 14 deletions(-) create mode 100644 docs/guide/usage.md diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index fe6adae..eceea8a 100644 --- a/docs/.vitepress/config.mjs +++ b/docs/.vitepress/config.mjs @@ -15,6 +15,7 @@ export default { items: [ { text: 'Getting Started', link: '/guide/getting-started' }, { text: 'Installation', link: '/guide/installation' }, + { text: 'Usage', link: '/guide/usage' }, { text: 'Configuration', link: '/guide/configuration' } ] }], diff --git a/docs/api/index.md b/docs/api/index.md index 5998622..9d61eb0 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -4,26 +4,57 @@ The SoroSave SDK exports the following modules: ## Modules -- [`SoroSaveClient`](/api/client) - Main client class -- [`Types`](/api/types) - TypeScript interfaces and types -- [`Utils`](/api/utils) - Utility functions +- [`SoroSaveClient`](/api/client) — Main client class for contract interaction +- [`Types`](/api/types) — TypeScript interfaces, types, and enums +- [`Utils`](/api/utils) — Utility functions for formatting and calculations -## Usage +## Quick Import ```typescript +// Core client import { SoroSaveClient } from '@sorosave/sdk'; -import type { CreateGroupParams, SavingsGroup } from '@sorosave/sdk'; + +// Types +import type { CreateGroupParams, SavingsGroup, RoundInfo, SoroSaveConfig } from '@sorosave/sdk'; + +// Enums +import { GroupStatus } from '@sorosave/sdk'; + +// Utilities +import { formatAmount, parseAmount, getStatusLabel } from '@sorosave/sdk'; + +// React hooks +import { SoroSaveProvider, useGroup, useContribute, useMemberGroups } from '@sorosave/react'; ``` -## Client Methods +## Client Methods Overview + +### Write Methods (Transactions) + +| Method | Description | Access | +|--------|-------------|--------| +| `createGroup()` | Create a new savings group | Anyone | +| `joinGroup()` | Join an existing group | Anyone | +| `leaveGroup()` | Leave a group (while forming) | Members | +| `startGroup()` | Start the savings cycle | Admin | +| `contribute()` | Contribute to current round | Members | +| `distributePayout()` | Distribute pot to recipient | Anyone | +| `pauseGroup()` | Pause a group | Admin | +| `resumeGroup()` | Resume a paused group | Admin | +| `raiseDispute()` | Raise a dispute | Members | + +### Read Methods (Queries) + +| Method | Description | Returns | +|--------|-------------|---------| +| `getGroup()` | Get group details | `SavingsGroup` | +| `getRoundStatus()` | Get round information | `RoundInfo` | +| `getMemberGroups()` | Get all groups for a member | `number[]` | + +### Batch & Utility Methods | Method | Description | |--------|-------------| -| `createGroup()` | Create a new savings group | -| `joinGroup()` | Join an existing group | -| `leaveGroup()` | Leave a group (while forming) | -| `startGroup()` | Start the savings cycle | -| `contribute()` | Make a contribution | -| `distribute()` | Distribute funds to recipient | -| `getGroup()` | Get group details | -| `getGroups()` | List all groups | +| `createBatchBuilder()` | Create a batch operation builder | +| `buildBatchTransaction()` | Build a transaction from batch operations | +| `setWalletAdapter()` | Set or change the wallet adapter | diff --git a/docs/guide/usage.md b/docs/guide/usage.md new file mode 100644 index 0000000..73e0166 --- /dev/null +++ b/docs/guide/usage.md @@ -0,0 +1,219 @@ +# Usage Guide + +Complete guide to using the SoroSave SDK for building savings group applications. + +## Initializing the Client + +```typescript +import { SoroSaveClient } from '@sorosave/sdk'; + +const client = new SoroSaveClient({ + rpcUrl: 'https://soroban-testnet.stellar.org', + contractId: 'CBQ...YOUR_CONTRACT_ID', + networkPassphrase: 'Test SDF Network ; September 2015' +}); +``` + +## Using with React + +The SDK provides React hooks for easy frontend integration: + +```tsx +import { SoroSaveProvider, useGroup, useContribute, useMemberGroups } from '@sorosave/react'; + +function App() { + return ( + + + + ); +} +``` + +### useGroup — Fetch Group Data + +```tsx +function GroupCard({ groupId }: { groupId: number }) { + const { group, loading, error, refetch } = useGroup(groupId); + + if (loading) return ; + if (error) return ; + if (!group) return ; + + return ( +
+

{group.name}

+

Members: {group.members.length}/{group.maxMembers}

+

Round: {group.currentRound}/{group.totalRounds}

+

Status: {group.status}

+ +
+ ); +} +``` + +### useContribute — Make Contributions + +```tsx +function ContributeButton({ groupId, member }: Props) { + const { contribute, loading, error } = useContribute(); + + const handleContribute = async () => { + try { + await contribute({ member, groupId }); + toast.success('Contribution successful!'); + } catch (err) { + toast.error(err.message); + } + }; + + return ( + + ); +} +``` + +### useMemberGroups — List Member's Groups + +```tsx +function MyGroups({ address }: { address: string }) { + const { groupIds, loading, refetch } = useMemberGroups(address); + + return ( +
+

My Groups ({groupIds.length})

+ {groupIds.map(id => )} + +
+ ); +} +``` + +## Wallet Integration + +### Freighter Wallet + +```typescript +import { SoroSaveClient } from '@sorosave/sdk'; +import { FreighterAdapter } from '@sorosave/sdk'; + +const wallet = new FreighterAdapter(); +const client = new SoroSaveClient(config, wallet); + +// Transactions will be automatically signed via Freighter +const tx = await client.createGroup(params, sourceAddress); +``` + +### Custom Wallet Adapter + +```typescript +import { WalletAdapter } from '@sorosave/sdk'; + +class MyWalletAdapter implements WalletAdapter { + async signTransaction(tx: Transaction, passphrase: string): Promise { + // Your custom signing logic + return signedTx; + } + + async getPublicKey(): Promise { + return 'G...'; + } +} +``` + +## Batch Operations + +The SDK supports batching multiple operations into a single transaction: + +```typescript +const batch = client.createBatchBuilder(); + +// Add multiple operations +batch.addJoinGroup(member1, groupId); +batch.addJoinGroup(member2, groupId); +batch.addJoinGroup(member3, groupId); + +// Build and submit as one transaction +const tx = await client.buildBatchTransaction(sourceAddress, batch); +``` + +## Utility Functions + +```typescript +import { + formatAmount, + parseAmount, + getStatusLabel, + shortenAddress, + calculatePotSize, + getPayoutRound +} from '@sorosave/sdk'; + +// Format token amounts for display +formatAmount(1000000000n, 7); // "100" + +// Parse user input to raw amount +parseAmount("100", 7); // 1000000000n + +// Get readable status +getStatusLabel(group.status); // "Active" + +// Shorten addresses for UI +shortenAddress('GABC...XYZ'); // "GABC...WXYZ" + +// Calculate total pot +calculatePotSize(1000000000n, 5); // 5000000000n + +// Find when a member gets paid +getPayoutRound(group.payoutOrder, memberAddress); // 3 +``` + +## Error Handling + +```typescript +try { + const tx = await client.contribute(member, groupId, sourceAddress); + const result = await server.submitTransaction(tx); +} catch (error) { + if (error.message.includes('Simulation failed')) { + console.error('Transaction simulation failed:', error); + } else if (error.message.includes('insufficient')) { + console.error('Insufficient balance'); + } else { + console.error('Unexpected error:', error); + } +} +``` + +## CLI Usage + +The SDK includes a command-line interface: + +```bash +# Install globally +npm install -g @sorosave/sdk + +# Create a group +sorosave create-group --name "My Group" --amount 100 --members 5 + +# Join a group +sorosave join-group --group-id 1 --member "G..." + +# Contribute +sorosave contribute --group-id 1 --member "G..." + +# Query group info +sorosave get-group --group-id 1 +``` + +## Next Steps + +- [API Reference](/api/) — Complete method documentation +- [Configuration](/guide/configuration) — Advanced configuration +- [Tutorial: Group Lifecycle](/tutorial/group-lifecycle) — Full walkthrough