geniebox-shared-lib 2.0.0 → 2.0.2

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/auth.interface.d.ts

@@ -81,6 +81,10 @@ export interface GetByIdRequest {
 export interface ResendConfirmationCodeRequest {
     userId: string;
 }
+export interface VerifyResetCodeRequest {
+    email: string;
+    code: string;
+}
 export declare const AUTH_PACKAGE_NAME = "auth";
 export declare const RegisterCredentials: MessageFns<RegisterCredentials>;
 export declare const LoginCredentials: MessageFns<LoginCredentials>;
@@ -99,6 +103,7 @@ export declare const CheckEmailVerifiedRequest: MessageFns<CheckEmailVerifiedReq
 export declare const CheckEmailVerifiedResponse: MessageFns<CheckEmailVerifiedResponse>;
 export declare const GetByIdRequest: MessageFns<GetByIdRequest>;
 export declare const ResendConfirmationCodeRequest: MessageFns<ResendConfirmationCodeRequest>;
+export declare const VerifyResetCodeRequest: MessageFns<VerifyResetCodeRequest>;
 export interface AuthServiceClient {
     profile(request: GetByIdRequest, metadata?: Metadata): Observable<UserResponse>;
     login(request: LoginCredentials, metadata?: Metadata): Observable<AuthResponse>;
@@ -106,6 +111,7 @@ export interface AuthServiceClient {
     refresh(request: RefreshRequest, metadata?: Metadata): Observable<AuthResponse>;
     logout(request: LogoutRequest, metadata?: Metadata): Observable<Empty>;
     recover(request: RecoverRequest, metadata?: Metadata): Observable<Empty>;
+    verifyResetCode(request: VerifyResetCodeRequest, metadata?: Metadata): Observable<Empty>;
     resetPassword(request: ResetPasswordRequest, metadata?: Metadata): Observable<Empty>;
     confirmEmail(request: ConfirmEmailRequest, metadata?: Metadata): Observable<ConfirmEmailResponse>;
     confirmEmailByCode(request: ConfirmEmailByCodeRequest, metadata?: Metadata): Observable<AuthResponse>;
@@ -119,6 +125,7 @@ export interface AuthServiceController {
     refresh(request: RefreshRequest, metadata?: Metadata): Promise<AuthResponse> | Observable<AuthResponse> | AuthResponse;
     logout(request: LogoutRequest, metadata?: Metadata): void;
     recover(request: RecoverRequest, metadata?: Metadata): void;
+    verifyResetCode(request: VerifyResetCodeRequest, metadata?: Metadata): void;
     resetPassword(request: ResetPasswordRequest, metadata?: Metadata): void;
     confirmEmail(request: ConfirmEmailRequest, metadata?: Metadata): Promise<ConfirmEmailResponse> | Observable<ConfirmEmailResponse> | ConfirmEmailResponse;
     confirmEmailByCode(request: ConfirmEmailByCodeRequest, metadata?: Metadata): Promise<AuthResponse> | Observable<AuthResponse> | AuthResponse;
@@ -183,6 +190,15 @@ export declare const AuthServiceService: {
         readonly responseSerialize: (value: Empty) => Buffer;
         readonly responseDeserialize: (value: Buffer) => Empty;
     };
+    readonly verifyResetCode: {
+        readonly path: "/auth.AuthService/verifyResetCode";
+        readonly requestStream: false;
+        readonly responseStream: false;
+        readonly requestSerialize: (value: VerifyResetCodeRequest) => Buffer;
+        readonly requestDeserialize: (value: Buffer) => VerifyResetCodeRequest;
+        readonly responseSerialize: (value: Empty) => Buffer;
+        readonly responseDeserialize: (value: Buffer) => Empty;
+    };
     readonly resetPassword: {
         readonly path: "/auth.AuthService/resetPassword";
         readonly requestStream: false;
@@ -236,6 +252,7 @@ export interface AuthServiceServer extends UntypedServiceImplementation {
     refresh: handleUnaryCall<RefreshRequest, AuthResponse>;
     logout: handleUnaryCall<LogoutRequest, Empty>;
     recover: handleUnaryCall<RecoverRequest, Empty>;
+    verifyResetCode: handleUnaryCall<VerifyResetCodeRequest, Empty>;
     resetPassword: handleUnaryCall<ResetPasswordRequest, Empty>;
     confirmEmail: handleUnaryCall<ConfirmEmailRequest, ConfirmEmailResponse>;
     confirmEmailByCode: handleUnaryCall<ConfirmEmailByCodeRequest, AuthResponse>;