echofi-client/README.md

A comprehensive TypeScript/JavaScript client library for EchoFi services with automatic gRPC-Web code generation, unified service access, and real-time WebSocket communication.

# EchoFi gRPC Client

A comprehensive TypeScript/JavaScript client library for EchoFi services with automatic gRPC-Web code generation and unified service access.

## 🚀 Features

- **Auto-Generated Client**: Automatically discovers and generates clients for all proto services
- **Unified Interface**: Single client instance provides access to all backend services
- **Type-Safe**: Full TypeScript support with generated types
- **Future-Proof**: Just add proto files and regenerate - no manual code changes needed
- **WebSocket Support**: Real-time communication capabilities
- **Cross-Platform**: Works in browsers (gRPC-Web) and Node.js (gRPC)

## 📦 Installation

```bash
npm install echofi-client
```

## 🔧 Quick Start

```typescript
import { EchoFiGrpcWebClient, Messages } from 'echofi-client';

// Initialize client
const client = new EchoFiGrpcWebClient({
  host: 'localhost',
  port: 8080
});

await client.initialize();

// Use Music Service
const request = new Messages.Music.Service.ListArtistsRequest();
request.setOffset(0);
request.setLimit(10);

const response = await client.music.listArtists(request);
const artists = response.getArtistsList();
const total = response.getTotal();

console.log('Artists:', artists.map(artist => ({
  id: artist.getArtistId(),
  name: artist.getName()
})));

console.log(`Showing ${artists.length} of ${total} total artists`);
```

## 📄 Pagination Support

All list endpoints include comprehensive pagination support with total count:

```typescript
// Example: Paginated artist listing
const request = new Messages.Music.Service.ListArtistsRequest();
request.setOffset(0);
request.setLimit(20);

const response = await client.music.listArtists(request);

// Access pagination data
const items = response.getArtistsList();
const total = response.getTotal();        // Total items matching criteria
const offset = response.getOffset();      // Current offset
const limit = response.getLimit();        // Current limit

// Calculate pagination info
const currentPage = Math.floor(offset / limit) + 1;
const totalPages = Math.ceil(total / limit);
const hasNextPage = offset + limit < total;
const hasPrevPage = offset > 0;

console.log(`Page ${currentPage} of ${totalPages} (${items.length} items, ${total} total)`);
```

### Pagination Pattern

All `List*Response` messages include these fields:
- `total: number` - Total count of items matching query criteria (before pagination)
- `offset: number` - Current offset used in the request
- `limit: number` - Current limit used in the request

## 🏗️ Development

### Adding New Services

1. Add your proto files to `proto/` directory
2. Run generation script:
   ```bash
   npm run generate-client
   ```
3. Your new service is automatically available in the unified client!

### Available Scripts

- `npm run generate-client` - Generate client from proto files and build
- `npm run build` - Build the library
- `npm run clean` - Clean generated files and dist
- `npm run dev` - Run in development mode

## 📚 API Reference

### Available Services

- **Music Service**: Artists, albums, tracks, genres
- **User Service**: User management and authentication
- **Activity Service**: Listening sessions, favorites, playlists
- **Stats Service**: User points, statistics, boosts

### Client Configuration

```typescript
interface EchoFiGrpcWebClientConfig {
  host?: string;        // Default: 'localhost'
  port?: number;        // Default: 8080
  secure?: boolean;     // Default: false
  credentials?: object; // gRPC credentials
  options?: object;     // gRPC options
}
```

## 🔄 Auto-Generation

The client automatically discovers all services in your proto directory and generates:

- Service clients with proper TypeScript types
- Message classes for requests/responses
- Unified client interface
- Helper methods for common operations

## 📄 License

MIT License - see LICENSE file for details.