echofi-client

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

npm install echofi-client

🔧 Quick Start

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:

// 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

• Add your proto files to proto/ directory
• Run generation script:

  npm run generate-client
  

• 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

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.