geniebox-shared-lib 1.0.74 → 2.0.1

package/README.md

@@ -0,0 +1,636 @@
+# GenieBox Shared Library
+
+A comprehensive shared NestJS library providing gRPC clients, interfaces, and utilities for the GenieBox microservices ecosystem. This library serves as the central communication layer between all GenieBox services.
+
+## Features
+
+- **gRPC Clients**: Pre-configured clients for all GenieBox services
+- **TypeScript Interfaces**: Fully typed interfaces for all service communications
+- **Protocol Buffers**: Auto-generated from proto files with type safety
+- **NestJS Integration**: Seamless integration with NestJS microservices
+- **Service Discovery**: Centralized service client management
+- **Error Handling**: Consistent error handling across all services
+- **Observable Support**: RxJS observables for reactive programming
+
+## Architecture
+
+### Core Components
+
+- **gRPC Clients**: Service-specific clients for communication
+- **Interfaces**: TypeScript interfaces for all service methods
+- **Shared Module**: NestJS module for easy integration
+- **Protocol Buffers**: Auto-generated from proto definitions
+- **Type Definitions**: Complete TypeScript type definitions
+
+### Supported Services
+
+- **User Service**: User management and authentication
+- **Auth Service**: Authentication and authorization
+- **AI Service**: AI processing and machine learning
+- **OpenAI Service**: OpenAI API integration
+- **Storage Service**: File storage and management
+- **Event Service**: Real-time event streaming
+- **Key Service**: API key management
+
+## Installation
+
+```bash
+# Install from npm registry
+npm install geniebox-shared-lib
+
+# Or install from local development
+npm install file:../libs/geniebox-shared
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { 
+  SharedModule, 
+  UsersClient, 
+  AuthClient, 
+  AIClient 
+} from 'geniebox-shared-lib';
+
+// Import in your NestJS module
+@Module({
+  imports: [SharedModule],
+  // ... other module configuration
+})
+export class YourModule {}
+```
+
+### Using gRPC Clients
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { UsersClient, CreateUserRequest } from 'geniebox-shared-lib';
+
+@Injectable()
+export class YourService {
+  constructor(private readonly usersClient: UsersClient) {}
+
+  async createUser(userData: CreateUserRequest) {
+    return await this.usersClient.createUser(userData);
+  }
+}
+```
+
+### Service-Specific Usage
+
+#### User Service
+
+```typescript
+import { 
+  UsersClient, 
+  CreateUserRequest, 
+  UserResponse 
+} from 'geniebox-shared-lib';
+
+// Create user
+const createUserRequest: CreateUserRequest = {
+  email: 'user@example.com',
+  password: 'securePassword',
+  firstName: 'John',
+  lastName: 'Doe'
+};
+
+const user: UserResponse = await usersClient.createUser(createUserRequest);
+```
+
+#### Auth Service
+
+```typescript
+import { 
+  AuthClient, 
+  LoginCredentials, 
+  AuthResponse 
+} from 'geniebox-shared-lib';
+
+// Login user
+const credentials: LoginCredentials = {
+  email: 'user@example.com',
+  password: 'securePassword',
+  rememberMe: true
+};
+
+const authResponse: AuthResponse = await authClient.login(credentials);
+```
+
+#### AI Service
+
+```typescript
+import { 
+  AIClient, 
+  AICallRequest, 
+  AICallResponse 
+} from 'geniebox-shared-lib';
+
+// Make AI request
+const aiRequest: AICallRequest = {
+  endpoint: '/ai/chat',
+  payload: { message: 'Hello, AI!' },
+  priority: 'normal'
+};
+
+const aiResponse: AICallResponse = await aiClient.call(aiRequest);
+```
+
+#### Storage Service
+
+```typescript
+import { 
+  StorageClient, 
+  UploadRequest, 
+  UploadResponse 
+} from 'geniebox-shared-lib';
+
+// Upload file
+const uploadRequest: UploadRequest = {
+  filename: 'document.pdf',
+  content: fileBuffer,
+  contentType: 'application/pdf'
+};
+
+const uploadResponse: UploadResponse = await storageClient.upload(uploadRequest);
+```
+
+#### Event Service
+
+```typescript
+import { 
+  EventClient, 
+  SubscribeRequest, 
+  EventMessage 
+} from 'geniebox-shared-lib';
+
+// Subscribe to events
+const subscribeRequest: SubscribeRequest = {
+  eventType: 'user.created',
+  userId: 'user-123'
+};
+
+const eventStream = eventClient.subscribe(subscribeRequest);
+eventStream.subscribe((event: EventMessage) => {
+  console.log('Received event:', event);
+});
+```
+
+#### Key Service
+
+```typescript
+import { 
+  KeyClient, 
+  CreateKeyRequest, 
+  KeyResponse 
+} from 'geniebox-shared-lib';
+
+// Create API key
+const createKeyRequest: CreateKeyRequest = {
+  name: 'My API Key',
+  permissions: ['read', 'write'],
+  expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000) // 30 days
+};
+
+const key: KeyResponse = await keyClient.createKey(createKeyRequest);
+```
+
+## Configuration
+
+### Environment Variables
+
+The shared library uses environment variables for service configuration:
+
+```bash
+# User Service
+USER_SERVICE_URL=grpc://user-service:50051
+
+# Auth Service
+AUTH_SERVICE_URL=grpc://auth-service:50052
+
+# AI Service
+AI_SERVICE_URL=grpc://ai-service:50053
+
+# OpenAI Service
+OPENAI_SERVICE_URL=grpc://openai-service:50054
+
+# Storage Service
+STORAGE_SERVICE_URL=grpc://storage-service:50055
+
+# Event Service
+EVENT_SERVICE_URL=grpc://event-service:50056
+
+# Key Service
+KEY_SERVICE_URL=grpc://key-service:50057
+```
+
+### Service Configuration
+
+```typescript
+import { Module } from '@nestjs/common';
+import { SharedModule } from 'geniebox-shared-lib';
+
+@Module({
+  imports: [
+    SharedModule.forRoot({
+      userService: {
+        url: process.env.USER_SERVICE_URL || 'grpc://localhost:50051',
+        options: {
+          keepalive: true,
+          keepaliveTimeMs: 30000,
+          keepaliveTimeoutMs: 5000,
+        }
+      },
+      authService: {
+        url: process.env.AUTH_SERVICE_URL || 'grpc://localhost:50052',
+        options: {
+          keepalive: true,
+          keepaliveTimeMs: 30000,
+          keepaliveTimeoutMs: 5000,
+        }
+      },
+      // ... other services
+    })
+  ],
+})
+export class AppModule {}
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js 18.x or higher
+- npm 9.x or higher
+- Protocol Buffers compiler (protoc)
+- TypeScript 5.x
+
+### Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Generate protobuf files
+npm run proto:gen
+
+# Build the library
+npm run build
+
+# Generate and build
+npm run generate
+```
+
+### Scripts
+
+| Script | Description |
+|--------|-------------|
+| `npm run build` | Build TypeScript to JavaScript |
+| `npm run proto:gen` | Generate TypeScript from proto files |
+| `npm run generate` | Generate proto files and build |
+| `npm run prepublishOnly` | Build before publishing |
+
+### Proto File Generation
+
+The library automatically generates TypeScript interfaces and clients from Protocol Buffer definitions:
+
+```bash
+# Generate from proto files
+npm run proto:gen
+
+# This command:
+# 1. Reads proto files from ../../protos/
+# 2. Generates TypeScript interfaces in src/
+# 3. Creates gRPC clients for each service
+```
+
+## API Reference
+
+### SharedModule
+
+The main NestJS module that provides all gRPC clients.
+
+```typescript
+@Module({
+  imports: [SharedModule],
+  providers: [YourService],
+})
+export class YourModule {}
+```
+
+### Service Clients
+
+#### UsersClient
+
+```typescript
+class UsersClient {
+  createUser(request: CreateUserRequest): Promise<UserResponse>
+  getUserById(request: GetByIdRequest): Promise<UserResponse>
+  updateUser(request: UpdateUserRequest): Promise<UserResponse>
+  deleteUser(request: GetByIdRequest): Promise<void>
+  findUserByEmail(request: FindByEmailRequest): Promise<UserResponse>
+  findUserByPhone(request: FindByPhoneRequest): Promise<UserResponse>
+  updateUserPersonal(request: UpdateUserPersonal): Promise<UserResponse>
+  updatePassword(request: UpdatePasswordRequest): Promise<void>
+  updateEmailVerification(request: UpdateEmailVerificationRequest): Promise<void>
+  getEmailVerificationStatus(request: GetEmailVerificationStatusRequest): Promise<EmailVerificationStatusResponse>
+}
+```
+
+#### AuthClient
+
+```typescript
+class AuthClient {
+  login(request: LoginCredentials): Promise<AuthResponse>
+  register(request: RegisterCredentials): Promise<AuthResponse>
+  logout(request: LogoutRequest): Promise<void>
+  refresh(request: RefreshRequest): Promise<RefreshTokenResponse>
+  recover(request: RecoverRequest): Promise<void>
+  resetPassword(request: ResetPasswordRequest): Promise<void>
+  confirmEmail(request: ConfirmEmailRequest): Promise<ConfirmEmailResponse>
+  confirmEmailByCode(request: ConfirmEmailByCodeRequest): Promise<AuthResponse>
+  checkEmailVerified(request: CheckEmailVerifiedRequest): Promise<CheckEmailVerifiedResponse>
+  resendConfirmationCode(request: ResendConfirmationCodeRequest): Promise<void>
+}
+```
+
+#### AIClient
+
+```typescript
+class AIClient {
+  call(request: AICallRequest): Promise<AICallResponse>
+  status(request: AIStatusRequest): Promise<AIStatusResponse>
+  result(request: AIResultRequest): Promise<AIResultResponse>
+  cancel(request: AICancelRequest): Promise<AICancelResponse>
+  stream(request: AIStreamRequest): Observable<AIStreamResponse>
+}
+```
+
+#### StorageClient
+
+```typescript
+class StorageClient {
+  upload(request: UploadRequest): Promise<UploadResponse>
+  download(request: DownloadRequest): Promise<DownloadResponse>
+  delete(request: DeleteRequest): Promise<DeleteResponse>
+}
+```
+
+#### EventClient
+
+```typescript
+class EventClient {
+  subscribe(request: SubscribeRequest): Observable<EventMessage>
+  publish(event: EventMessage): Promise<void>
+}
+```
+
+#### KeyClient
+
+```typescript
+class KeyClient {
+  createKey(request: CreateKeyRequest): Promise<KeyResponse>
+  getKeyById(request: GetKeyByIdRequest): Promise<KeyResponse>
+  updateKey(request: UpdateKeyRequest): Promise<KeyResponse>
+  removeKey(request: RemoveKeyRequest): Promise<void>
+  getKeysByUser(request: GetKeysByUserRequest): Promise<KeysResponse>
+}
+```
+
+## Error Handling
+
+The library provides consistent error handling across all services:
+
+```typescript
+import { RpcException } from '@nestjs/microservices';
+
+try {
+  const user = await usersClient.createUser(request);
+} catch (error) {
+  if (error instanceof RpcException) {
+    // Handle gRPC errors
+    console.error('gRPC Error:', error.message);
+  } else {
+    // Handle other errors
+    console.error('Unexpected error:', error);
+  }
+}
+```
+
+## Type Safety
+
+All interfaces are fully typed with TypeScript:
+
+```typescript
+// Fully typed request/response objects
+interface CreateUserRequest {
+  email: string;
+  password: string;
+  firstName: string;
+  lastName: string;
+  phone?: string;
+  dateOfBirth?: Date;
+}
+
+interface UserResponse {
+  id: string;
+  email: string;
+  firstName: string;
+  lastName: string;
+  phone?: string;
+  dateOfBirth?: Date;
+  createdAt: Date;
+  updatedAt: Date;
+}
+```
+
+## Performance
+
+### Connection Pooling
+
+The library uses gRPC connection pooling for optimal performance:
+
+```typescript
+// Configure connection options
+const clientOptions = {
+  keepalive: true,
+  keepaliveTimeMs: 30000,
+  keepaliveTimeoutMs: 5000,
+  keepalivePermitWithoutCalls: true,
+  maxReceiveMessageLength: 4 * 1024 * 1024, // 4MB
+  maxSendMessageLength: 4 * 1024 * 1024,    // 4MB
+};
+```
+
+### Caching
+
+Service clients can be configured with caching:
+
+```typescript
+// Enable client-side caching
+const usersClient = new UsersClient(serviceUrl, {
+  ...clientOptions,
+  cache: {
+    enabled: true,
+    ttl: 300000, // 5 minutes
+  }
+});
+```
+
+## Testing
+
+### Unit Testing
+
+```typescript
+import { Test, TestingModule } from '@nestjs/testing';
+import { SharedModule, UsersClient } from 'geniebox-shared-lib';
+
+describe('YourService', () => {
+  let service: YourService;
+  let usersClient: UsersClient;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      imports: [SharedModule],
+      providers: [YourService],
+    }).compile();
+
+    service = module.get<YourService>(YourService);
+    usersClient = module.get<UsersClient>(UsersClient);
+  });
+
+  it('should create user', async () => {
+    const mockUser = { id: '1', email: 'test@example.com' };
+    jest.spyOn(usersClient, 'createUser').mockResolvedValue(mockUser);
+
+    const result = await service.createUser({ email: 'test@example.com' });
+    expect(result).toEqual(mockUser);
+  });
+});
+```
+
+### Integration Testing
+
+```typescript
+import { Test, TestingModule } from '@nestjs/testing';
+import { SharedModule } from 'geniebox-shared-lib';
+
+describe('Integration Tests', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    const moduleFixture: TestingModule = await Test.createTestingModule({
+      imports: [SharedModule],
+    }).compile();
+
+    app = moduleFixture.createNestApplication();
+    await app.init();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it('should connect to services', async () => {
+    // Test actual service connections
+  });
+});
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### Connection Errors
+
+```bash
+# Check service URLs
+echo $USER_SERVICE_URL
+echo $AUTH_SERVICE_URL
+
+# Test gRPC connectivity
+grpcurl -plaintext localhost:50051 list
+```
+
+#### Type Errors
+
+```bash
+# Regenerate types from proto files
+npm run proto:gen
+
+# Rebuild the library
+npm run build
+```
+
+#### Import Errors
+
+```typescript
+// Ensure correct imports
+import { UsersClient, CreateUserRequest } from 'geniebox-shared-lib';
+
+// Not from individual files
+// import { UsersClient } from 'geniebox-shared-lib/src/user.client';
+```
+
+### Debug Mode
+
+```typescript
+// Enable gRPC debug logging
+process.env.GRPC_VERBOSITY = 'DEBUG';
+process.env.GRPC_TRACE = 'all';
+
+// Enable client debug mode
+const client = new UsersClient(serviceUrl, {
+  ...options,
+  debug: true,
+});
+```
+
+## Contributing
+
+### Development Setup
+
+1. Fork the repository
+2. Create a feature branch
+3. Install dependencies: `npm install`
+4. Make your changes
+5. Run tests: `npm test`
+6. Submit a pull request
+
+### Code Standards
+
+- **TypeScript**: Strict type checking enabled
+- **ESLint**: Code linting with TypeScript rules
+- **Prettier**: Code formatting
+- **Testing**: All new code must include tests
+- **Documentation**: JSDoc comments for public APIs
+
+### Adding New Services
+
+1. Add proto file to `../../protos/`
+2. Run `npm run proto:gen` to generate interfaces
+3. Create client class in `src/`
+4. Export from `src/index.ts`
+5. Update `SharedModule` to include new client
+6. Add tests for new client
+
+## License
+
+This project is licensed under the ISC License - see the package.json file for details.
+
+## Support
+
+For support and questions:
+
+- **Issues**: Create a GitHub issue
+- **Documentation**: Check this README and inline JSDoc
+- **Logs**: Review gRPC connection logs
+- **Debug**: Enable debug mode for detailed logging
+
+---
+
+**Version**: 2.0.0  
+**Last Updated**: January 2024  
+**Maintainer**: GenieBox Team

package/dist/{ai/ai.interface.d.ts → ai.interface.d.ts}

@@ -8,11 +8,6 @@ export interface AICallResponse {
 export interface AIStatusResponse {
     requestId: string;
     status: string;
-    logs?: Array<{
-        message: string;
-        level?: 'info' | 'warn' | 'error';
-        timestamp?: string;
-    }>;
 }
 export interface AIResultResponse {
     requestId: string;

package/dist/index.d.ts

@@ -1,15 +1,15 @@
 export { SharedModule } from "./shared.module";
-export { UsersClient } from "./user/user.client";
-export { AuthClient } from "./auth/auth.client";
-export { AIClient } from "./ai/ai.client";
-export { OpenAIClient } from "./openai/openai.client";
-export { FileClient } from "./file/file.client";
-export { EventClient } from "./event/event.client";
-export { KeyClient } from "./key/key.client";
-export { MessageFns as UserMessageFns, protobufPackage as UserProtobufPackage, User, CreateUserRequest, CreateUserPersonal, UpdateUserRequest, GetByIdRequest, UserResponse, UsersResponse, FindByEmailRequest, FindByPhoneRequest, UpdateUserPersonal, UpdatePasswordRequest, UpdateEmailVerificationRequest, ResetPasswordData, GetEmailVerificationStatusRequest, EmailVerificationStatusResponse, UserServiceService as UserService, } from "./user/user.interface";
-export { MessageFns as AuthMessageFns, protobufPackage as AuthProtobufPackage, LoginCredentials, RegisterCredentials, LogoutRequest, RefreshRequest, AuthResponse, RefreshTokenResponse, RecoverRequest, ResetPasswordRequest, ConfirmEmailRequest, ConfirmEmailByCodeRequest, ConfirmEmailResponse, CheckEmailVerifiedRequest, CheckEmailVerifiedResponse, ResendConfirmationCodeRequest, } from "./auth/auth.interface";
-export { MessageFns as AIMessageFns, protobufPackage as AIProtobufPackage, AICallRequest, AICallResponse, AIStatusRequest, AIStatusResponse, AIResultRequest, AIResultResponse, AICancelRequest, AICancelResponse, AIStreamRequest, AIStreamResponse, AIServiceService as AIService, } from "./ai/ai.interface";
-export { MessageFns as OpenAIMessageFns, protobufPackage as OpenAIProtobufPackage, CreateRequest as OpenAICreateRequest, CreateResponse as OpenAICreateResponse, OpenAIServiceService as OpenAIService, } from "./openai/openai.interface";
-export { UploadRequest, UploadResponse, DownloadRequest, DownloadResponse, DeleteRequest, DeleteResponse, FileServiceService as FileService, protobufPackage as FileProtobufPackage, } from "./file/file.interface";
-export { MessageFns as EventMessageFns, protobufPackage as EventProtobufPackage, SubscribeRequest, EventMessage, EventServiceService as EventService, } from "./event/event.interface";
-export { MessageFns as KeysMessageFns, protobufPackage as KeysProtobufPackage, Key, CreateKeyRequest, UpdateKeyRequest, RemoveKeyRequest, GetKeyByIdRequest, KeyResponse, KeysResponse, GetKeysByUserRequest, KeyServiceService as KeyService, } from "./key/key.interface";
+export { UsersClient } from "./user.client";
+export { AuthClient } from "./auth.client";
+export { AIClient } from "./ai.client";
+export { OpenAIClient } from "./openai.client";
+export { StorageClient } from "./storage.client";
+export { EventClient } from "./event.client";
+export { KeyClient } from "./key.client";
+export { MessageFns as UserMessageFns, protobufPackage as UserProtobufPackage, User, CreateUserRequest, CreateUserPersonal, UpdateUserRequest, FindOneRequest, UserResponse, UsersResponse, FindByEmailRequest, FindByPhoneRequest, UpdateUserPersonal, UpdatePasswordRequest, UpdateEmailVerificationRequest, ResetPasswordData, GetEmailVerificationStatusRequest, EmailVerificationStatusResponse, FindUsersByIdsRequest, UserServiceService as UserService, } from "./user.interface";
+export { MessageFns as AuthMessageFns, protobufPackage as AuthProtobufPackage, LoginCredentials, RegisterCredentials, LogoutRequest, RefreshRequest, AuthResponse, RefreshTokenResponse, RecoverRequest, ResetPasswordRequest, ConfirmEmailRequest, ConfirmEmailByCodeRequest, ConfirmEmailResponse, CheckEmailVerifiedRequest, CheckEmailVerifiedResponse, ResendConfirmationCodeRequest, } from "./auth.interface";
+export { MessageFns as AIMessageFns, protobufPackage as AIProtobufPackage, AICallRequest, AICallResponse, AIStatusRequest, AIStatusResponse, AIResultRequest, AIResultResponse, AICancelRequest, AICancelResponse, AIStreamRequest, AIStreamResponse, AIServiceService as AIService, } from "./ai.interface";
+export { MessageFns as OpenAIMessageFns, protobufPackage as OpenAIProtobufPackage, CreateRequest as OpenAICreateRequest, CreateResponse as OpenAICreateResponse, OpenAIServiceService as OpenAIService, } from "./openai.interface";
+export { UploadRequest, UploadResponse, DownloadRequest, DownloadResponse, DeleteRequest, DeleteResponse, StorageServiceService as StorageService, protobufPackage as FileProtobufPackage, } from "./storage.interface";
+export { MessageFns as EventMessageFns, protobufPackage as EventProtobufPackage, SubscribeRequest, EventMessage, EventServiceService as EventService, } from "./event.interface";
+export { MessageFns as KeysMessageFns, protobufPackage as KeysProtobufPackage, Key, CreateKeyRequest, UpdateKeyRequest, RemoveKeyRequest, GetKeyByIdRequest, KeyResponse, KeysResponse, GetKeysByUserRequest, KeyServiceService as KeyService, } from "./key.interface";