Add escrow fund(), disputeEscrow(), ProfileClient, and Typedoc config

.gitignore

@@ -5,6 +5,7 @@ dist/
 coverage/
 *.js.map
 *.tsbuildinfo
+docs/reference/
 
 # IDE
 dist

CHANGELOG.md

@@ -1,6 +1,23 @@
 # Changelog
 
 ## [Unreleased]
+- Added `TrustFlowEscrowClient.fund()` (#4) — funds an existing escrow by encoding a token
+  transfer (e.g. the USDC Soroban token contract) into contract call arguments via the new
+  `buildFundArgs`; omit `tokenAddress` to use the escrow's native asset.
+- Added `ProfileClient` (#5) — type-safe Axios methods (`getProfile`/`updateProfile`) for the
+  backend's `/profiles` endpoints, following the same retry-aware `SDKResult` pattern as
+  `DisputeClient`/`JurorClient`. Exported from the package root alongside `Profile` and
+  `UpdateProfileParams`.
+- Added `disputeEscrow()` to `src/escrow/dispute.ts` (#6) — the on-chain counterpart to
+  `DisputeClient.raiseDispute` (which posts to the backend API); simplifies the XDR construction
+  for alerting the smart contract of a dispute via the existing `buildDisputeArgs`. This also
+  fixes `examples/dispute.ts`, which already imported `disputeEscrow` from this module even
+  though it was never implemented.
+- Added a Typedoc configuration (#7) — `typedoc.json` plus `npm run docs` / `docs:watch` —
+  auto-generating API reference HTML from JSDoc comments into `docs/reference` (gitignored,
+  generated on demand). `skipErrorChecking` is enabled so doc generation isn't blocked by
+  pre-existing unrelated compiler diagnostics in legacy browser-wallet code (`window` usage
+  without a DOM lib, etc.).
 - Exported the Zod validation schemas from `src/schemas.ts` (`StellarAddressSchema`,
   `ContractIdSchema`, `StroopsSchema`, `NetworkSchema`, `CreateEscrowSchema`,
   `ReleaseEscrowSchema`, `DisputeEscrowSchema`, `ClientConfigSchema`, plus the `*Input` inferred

README.md

@@ -62,7 +62,7 @@ if (result.ok) {
 ### 3 — Fund & Release an Escrow
 
 ```typescript
-import { TrustFlowClient } from '@trustflow/sdk';
+import { TrustFlowClient, TrustFlowEscrowClient } from '@trustflow/sdk';
 import { createEscrow, releaseEscrow } from '@trustflow/sdk/escrow';
 import { connectWallet } from '@trustflow/sdk/wallet';
 import { xlmToStroops } from '@trustflow/sdk/utils';
@@ -84,6 +84,21 @@ const escrow = await createEscrow(client, {
 });
 console.log('Escrow created:', escrow.id);
 
+// Fund (e.g. lock USDC via its Soroban token contract instead of the native asset)
+const escrowClient = new TrustFlowEscrowClient({
+  contractId: process.env.TRUSTFLOW_CONTRACT_ID!,
+  network: 'TESTNET',
+  rpcUrl: 'https://soroban-testnet.stellar.org',
+  networkPassphrase: 'Test SDF Network ; September 2015',
+});
+const funded = await escrowClient.fund(
+  escrow.id,
+  wallet.publicKey,
+  xlmToStroops('50'),
+  process.env.USDC_CONTRACT_ID,
+);
+if (funded.ok) console.log('Funded! tx:', funded.data.txHash);
+
 // Release
 const txHash = await releaseEscrow(client, {
   escrowId: escrow.id,
@@ -173,6 +188,22 @@ const result = await escrowClient.claim('esc-42', 'GBENEFICIARY...');
 if (result.ok) console.log('Claimed! tx:', result.data.txHash);
 ```
 
+### User Profiles
+
+`ProfileClient` wraps the backend's `/profiles` endpoints with the same retry-aware transport
+as `DisputeClient`/`JurorClient`:
+
+```typescript
+import { ProfileClient } from '@trustflow/sdk';
+
+const profiles = new ProfileClient(process.env.TRUSTFLOW_API_URL!, authToken);
+
+const result = await profiles.getProfile(wallet.publicKey);
+if (result.ok) console.log(result.data.displayName);
+
+await profiles.updateProfile(wallet.publicKey, { bio: 'Building on Stellar' });
+```
+
 ### IPFS Storage
 
 Every `TrustFlowClient` exposes a built-in `storage.upload()` helper for pinning files to
@@ -300,6 +331,8 @@ import { useWallet, useBalance, useTransaction } from '@trustflow/sdk/react';
 - **[API Reference](./docs/API.md)** — Complete API documentation
 - **[Architecture](./docs/ARCHITECTURE.md)** — Design principles and module structure
 - **[Examples](./examples/)** — Working code examples for common use cases
+- **API reference (generated)** — run `npm run docs` to build a browsable HTML API reference
+  from JSDoc comments into `docs/reference/` (not committed; regenerate locally or in CI)
 
 ---
 

docs/API.md

@@ -2,11 +2,25 @@
 
 ## TrustFlowEscrowClient
 - `createEscrow(params)` — create a new escrow; encodes contract call arguments via `buildCreateEscrowArgs`
+- `fund(escrowId, funderAddress, amountStroops, tokenAddress?)` — transfer an asset (e.g. USDC via
+  its Soroban token contract) into an existing escrow to be locked until release; encodes contract
+  call arguments via `buildFundArgs`. Omit `tokenAddress` to use the escrow's native asset.
 - `releaseEscrow(id, signer)` — release funds to beneficiary
 - `claim(escrowId, claimantAddress)` — beneficiary-side shortcut to withdraw already-cleared escrow funds
 - `getEscrow(id)` — read escrow state from contract
 - `getGigs(params)` — fetch paginated gigs via backend API with automatic retries for transient failures (`429`, `5xx`, network)
 
+## disputeEscrow (`src/escrow/dispute.ts`)
+- `disputeEscrow(client, { escrowId, caller, reason })` — raises a dispute directly against the
+  TrustFlow contract; encodes contract call arguments via `buildDisputeArgs`. Distinct from
+  `DisputeClient.raiseDispute` below, which records the dispute with the backend API instead of
+  the on-chain contract.
+
+## ProfileClient
+- `new ProfileClient(apiUrl, token, options?)`
+- `.getProfile(address)` — fetch a user's profile (automatic retry on transient backend failures)
+- `.updateProfile(address, params)` — update a user's profile (automatic retry on transient backend failures)
+
 ## IPFSStorage
 - `new IPFSStorage(config?)` — `config.apiUrl` (default: web3.storage-compatible upload API), `config.apiKey`, `config.gatewayUrl`
 - `.upload(file, options?)` — uploads a `Buffer`/`Uint8Array`; returns `SDKResult<{ cid, url }>`