@okutrade/account-api/README.md

TypeScript client for OKU Account API using Connect-ES

# @oku/account-client

TypeScript client for the OKU Account API built with [Connect-ES](https://connectrpc.com/docs/web/getting-started).

## Installation

```bash
npm install @oku/account-client @connectrpc/connect @connectrpc/connect-web
```

## Usage

### Basic Setup

```typescript
import { createClient } from "@connectrpc/connect";
import { createConnectTransport } from "@connectrpc/connect-web";
import { AuthService, TokensService } from "@oku/account-client";

// Create a transport
const transport = createConnectTransport({
  baseUrl: "https://api.oku.trade/connect", // Replace with your API endpoint
});

// Create clients for the services you need
const authClient = createClient(AuthService, transport);
const tokensClient = createClient(TokensService, transport);
```

### Authentication

```typescript
import { AuthService } from "@oku/account-client";

const authClient = createClient(AuthService, transport);

// Validate a JWT token
const response = await authClient.validateToken({
  token: "your-jwt-token-here"
});

if (response.isValid) {
  console.log("Token is valid for user:", response.userId);
}
```

### Token Search

```typescript
import { SearchService } from "@oku/account-client";

const searchClient = createClient(SearchService, transport);

// Search for tokens
const tokens = await searchClient.searchTokens({
  query: "USDC",
  chainIds: [1, 10, 137], // Ethereum, Optimism, Polygon
  limit: 10
});

console.log("Found tokens:", tokens.tokens);
```

### Swap History

```typescript
import { SwapHistoryService } from "@oku/account-client";

const historyClient = createClient(SwapHistoryService, transport);

// Get swap history for an address
const history = await historyClient.getSwapHistory({
  addresses: [{ address: "0x742d35Cc6634C0532925a3b8D000AD5B5f1F4543" }],
  chainIds: [1, 10],
  limit: 50
});

console.log("Swap history:", history.trades);
```

### Special Orders

```typescript
import { SpecialOrdersService } from "@oku/account-client";

const ordersClient = createClient(SpecialOrdersService, transport);

// Get unified order history across chains
const orders = await ordersClient.unifiedHistory({
  addresses: [{ address: "0x742d35Cc6634C0532925a3b8D000AD5B5f1F4543" }],
  chainIds: [1, 10, 137]
});

console.log("Order history:", orders.orders);
```

## Available Services

- **AuthService** - Authentication and authorization
- **BridgeService** - Cross-chain bridge operations
- **CanoeService** - Quote tracking for swaps and bridges
- **LoginService** - Wallet-based authentication
- **OrdersService** - Order management
- **PreferencesService** - User preferences
- **RewardsService** - Rewards and points system
- **SearchService** - Token and pool search
- **SpecialOrdersService** - Unified order history
- **SwapHistoryService** - Trading history
- **TelemetryService** - Analytics and telemetry
- **TokensService** - Token information and metadata
- **WalletService** - Wallet management

## Modular Imports

You can import specific services to reduce bundle size:

```typescript
// Import specific services
import { AuthService } from "@oku/account-client/auth";
import { TokensService } from "@oku/account-client/tokens";
import { SearchService } from "@oku/account-client/search";

// Or import types only
import type { 
  SearchTokensRequest, 
  SearchTokensResponse 
} from "@oku/account-client";
```

## Error Handling

Connect-ES provides structured error handling:

```typescript
import { ConnectError } from "@connectrpc/connect";

try {
  const response = await authClient.validateToken({ token: "invalid" });
} catch (error) {
  if (error instanceof ConnectError) {
    console.error("API Error:", error.code, error.message);
    console.error("Details:", error.details);
  }
}
```

## TypeScript Support

This package provides full TypeScript support with generated types for all request/response messages and service interfaces.

```typescript
import type { 
  ValidateTokenRequest,
  ValidateTokenResponse,
  SearchTokensRequest,
  TokenResult
} from "@oku/account-client";

// All types are fully typed and have IntelliSense support
```

## Development

To build the package:

```bash
npm run build
```

To run type checking:

```bash
npm run typecheck
```

## License

MIT