@themainstack/communication 1.0.0

package/docs/INTEGRATION_EXAMPLE.md

@@ -0,0 +1,364 @@
+# Detailed Integration Example: fee-service ↔ payment-service
+
+This document shows exactly how to integrate two services using `@themainstack/communication`.
+
+---
+
+## Part 1: Fee Service (The Server)
+
+### 1.1 Install the Package
+
+```bash
+cd fee-service
+yarn add @themainstack/communication
+```
+
+### 1.2 Your Existing Business Logic
+
+```typescript
+// fee-service/src/fee/fees.service.ts
+import { Injectable } from '@nestjs/common';
+
+@Injectable()
+export class FeesService {
+  async calculateFeesForPlan(
+    planSlug: string,
+    currency: string,
+    amount: number,
+    type: string,
+  ) {
+    // Your existing business logic...
+    const feePercentage = planSlug === 'starter' ? 2.5 : 1.5;
+    const fee = amount * (feePercentage / 100);
+    
+    return {
+      dollarAmount: amount,
+      dollarTransactionFee: fee,
+      localTransactionFee: fee * 400, // Example: NGN rate
+      localCurrency: currency,
+      localAmount: (amount - fee).toString(),
+      exchangeRate: 400,
+      appliedFees: [{
+        id: 'fee_001',
+        type: 'withdrawal',
+        displayName: 'Withdrawal Fee',
+        amount: fee,
+        amountType: 'percent',
+      }],
+      appliedFeeIds: ['fee_001'],
+    };
+  }
+}
+```
+
+### 1.3 Create the gRPC Bootstrap File
+
+```typescript
+// fee-service/src/grpc/grpc-bootstrap.ts
+import { GrpcServerFactory } from '@themainstack/communication';
+import { FeesService } from '../fee/fees.service';
+
+const feesService = new FeesService();
+
+export async function startGrpcServer() {
+  const server = await GrpcServerFactory.createServer({
+    packageName: 'fee.v1',
+    serviceName: 'FeeService',
+    port: parseInt(process.env.GRPC_PORT || '50053'),
+    protoOutputDir: './src/grpc',
+  }, [
+    {
+      name: 'CalculateWithdrawalFee',
+      handler: async (request: any) => {
+        // Call your existing service
+        const result = await feesService.calculateFeesForPlan(
+          'starter', // Default to starter plan
+          request.currency,
+          request.amount,
+          'withdrawal',
+        );
+        
+        // Map to proto response format
+        return {
+          dollar_amount: result.dollarAmount,
+          dollar_transaction_fee: result.dollarTransactionFee,
+          local_transaction_fee: result.localTransactionFee,
+          local_currency: result.localCurrency,
+          local_amount: result.localAmount,
+          exchange_rate: result.exchangeRate,
+          applied_fees: result.appliedFees.map(f => ({
+            id: f.id,
+            type: f.type,
+            display_name: f.displayName,
+            amount: f.amount,
+            amount_type: f.amountType,
+          })),
+          applied_fee_ids: result.appliedFeeIds,
+        };
+      },
+      // Sample data for proto generation
+      requestSample: () => ({
+        merchantId: '',
+        amount: 0,
+        currency: '',
+        payoutMethod: '',
+      }),
+      responseSample: () => ({
+        dollarAmount: 0,
+        dollarTransactionFee: 0,
+        localTransactionFee: 0,
+        localCurrency: '',
+        localAmount: '',
+        exchangeRate: 0,
+        appliedFees: [{
+          id: '',
+          type: '',
+          displayName: '',
+          amount: 0,
+          amountType: '',
+        }],
+        appliedFeeIds: [''],
+      }),
+    },
+  ]);
+
+  await server.start();
+  return server;
+}
+```
+
+### 1.4 Integrate with main.ts
+
+```typescript
+// fee-service/src/main.ts
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+import { startGrpcServer } from './grpc/grpc-bootstrap';
+
+async function bootstrap() {
+  // Start HTTP server (existing)
+  const app = await NestFactory.create(AppModule);
+  const httpPort = process.env.PORT || 40400;
+  await app.listen(httpPort);
+  console.log(`HTTP server on port ${httpPort}`);
+
+  // Start gRPC server (new)
+  await startGrpcServer();
+}
+
+bootstrap();
+```
+
+### 1.5 Result
+
+When you start fee-service, it will:
+1. Auto-generate `./src/grpc/fee.proto`
+2. Start HTTP on port 40400
+3. Start gRPC on port 50053
+
+---
+
+## Part 2: Payment Service (The Client)
+
+### 2.1 Install the Package
+
+```bash
+cd payment-service
+yarn add @themainstack/communication
+```
+
+### 2.2 Copy the Proto File
+
+Copy the generated proto from fee-service:
+```bash
+mkdir -p src/payouts/protos
+cp ../fee-service/src/grpc/fee.proto src/payouts/protos/
+```
+
+### 2.3 Create the Fee Client
+
+```typescript
+// payment-service/src/payouts/clients/fee.client.ts
+import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
+import { GrpcClientFactory, handleGrpcError } from '@themainstack/communication';
+import { join } from 'path';
+
+export interface FeeCalculation {
+  dollarAmount: number;
+  dollarTransactionFee: number;
+  localTransactionFee: number;
+  localCurrency: string;
+  localAmount: string;
+  exchangeRate: number;
+  appliedFees: any[];
+  appliedFeeIds: string[];
+}
+
+@Injectable()
+export class FeeClient implements OnModuleInit {
+  private readonly logger = new Logger(FeeClient.name);
+  private client: any;
+
+  onModuleInit() {
+    const FEE_SERVICE_URL = process.env.FEE_SERVICE_GRPC_URL || 'localhost:50053';
+    
+    this.client = GrpcClientFactory.createClient({
+      serviceName: 'FeeService',
+      packageName: 'fee.v1',
+      protoPath: join(__dirname, '../protos/fee.proto'),
+      url: FEE_SERVICE_URL,
+    });
+
+    this.logger.log(`Fee gRPC Client connected to ${FEE_SERVICE_URL}`);
+  }
+
+  async calculateWithdrawalFee(
+    merchantId: string,
+    amount: number,
+    currency: string,
+    payoutMethod: string,
+  ): Promise<FeeCalculation> {
+    return new Promise((resolve, reject) => {
+      this.client.CalculateWithdrawalFee(
+        {
+          merchant_id: merchantId,
+          amount,
+          currency,
+          payout_method: payoutMethod,
+        },
+        (err: any, response: any) => {
+          if (err) {
+            try {
+              handleGrpcError(err);
+            } catch (normalizedError: any) {
+              this.logger.error(`Fee calculation failed: ${normalizedError.message}`);
+              reject(normalizedError);
+            }
+            return;
+          }
+
+          // Map snake_case response to camelCase
+          resolve({
+            dollarAmount: response.dollar_amount,
+            dollarTransactionFee: response.dollar_transaction_fee,
+            localTransactionFee: response.local_transaction_fee,
+            localCurrency: response.local_currency,
+            localAmount: response.local_amount,
+            exchangeRate: response.exchange_rate,
+            appliedFees: response.applied_fees || [],
+            appliedFeeIds: response.applied_fee_ids || [],
+          });
+        }
+      );
+    });
+  }
+}
+```
+
+### 2.4 Register in Module
+
+```typescript
+// payment-service/src/payouts/payouts.module.ts
+import { Module } from '@nestjs/common';
+import { PayoutsService } from './payouts.service';
+import { FeeClient } from './clients/fee.client';
+
+@Module({
+  providers: [PayoutsService, FeeClient],
+  exports: [PayoutsService],
+})
+export class PayoutsModule {}
+```
+
+### 2.5 Use in Your Service
+
+```typescript
+// payment-service/src/payouts/payouts.service.ts
+import { Injectable } from '@nestjs/common';
+import { FeeClient } from './clients/fee.client';
+
+@Injectable()
+export class PayoutsService {
+  constructor(private readonly feeClient: FeeClient) {}
+
+  async processPayout(merchantId: string, amount: number, currency: string) {
+    // Call fee-service via gRPC
+    const feeCalculation = await this.feeClient.calculateWithdrawalFee(
+      merchantId,
+      amount,
+      currency,
+      'bank_transfer',
+    );
+
+    console.log('Fee:', feeCalculation.dollarTransactionFee);
+    console.log('Net Amount:', amount - feeCalculation.dollarTransactionFee);
+
+    // Continue with payout logic...
+    return {
+      grossAmount: amount,
+      fee: feeCalculation.dollarTransactionFee,
+      netAmount: amount - feeCalculation.dollarTransactionFee,
+    };
+  }
+}
+```
+
+---
+
+## Part 3: Environment Configuration
+
+### fee-service/.env
+```env
+PORT=40400
+GRPC_PORT=50053
+```
+
+### payment-service/.env
+```env
+PORT=40401
+FEE_SERVICE_GRPC_URL=localhost:50053
+# In Docker/K8s: FEE_SERVICE_GRPC_URL=fee-service:50053
+```
+
+---
+
+## Part 4: Testing the Integration
+
+### Start fee-service
+```bash
+cd fee-service
+yarn start:dev
+# Output:
+# HTTP server on port 40400
+# 🚀 gRPC Server running on 0.0.0.0:50053
+```
+
+### Start payment-service
+```bash
+cd payment-service
+yarn start:dev
+# Output:
+# Fee gRPC Client connected to localhost:50053
+```
+
+### Make a Request
+```bash
+curl -X POST http://localhost:40401/payouts/process \
+  -H "Content-Type: application/json" \
+  -d '{"merchantId": "m123", "amount": 1000, "currency": "USD"}'
+
+# Response:
+# { "grossAmount": 1000, "fee": 25, "netAmount": 975 }
+```
+
+---
+
+## Summary
+
+| Step | fee-service | payment-service |
+|------|-------------|-----------------|
+| 1 | Install package | Install package |
+| 2 | Write business function | Copy proto file |
+| 3 | Use `GrpcServerFactory` | Use `GrpcClientFactory` |
+| 4 | Add to main.ts | Create client class |
+| 5 | Proto auto-generated! | Call client methods |

package/examples/full-grpc-demo.ts

@@ -0,0 +1,139 @@
+/**
+ * Full Demo: gRPC Server + Client using @themainstack/communication
+ * 
+ * This demonstrates the complete workflow:
+ * 1. Define a function you want to expose
+ * 2. Create a gRPC server (proto auto-generated)
+ * 3. Create a client to call the server
+ */
+
+import { GrpcServerFactory, GrpcClientFactory, handleGrpcError } from '../src';
+import * as path from 'path';
+
+// 1: Define your business logic function
+
+interface FeeRequest {
+    merchantId: string;
+    amount: number;
+    currency: string;
+}
+
+interface FeeResponse {
+    originalAmount: number;
+    fee: number;
+    totalAmount: number;
+    currency: string;
+    feePercentage: number;
+}
+
+// Your existing business function
+async function calculateFee(request: FeeRequest): Promise<FeeResponse> {
+    const feePercentage = 2.5; // 2.5% fee
+    const fee = request.amount * (feePercentage / 100);
+
+    return {
+        originalAmount: request.amount,
+        fee: fee,
+        totalAmount: request.amount + fee,
+        currency: request.currency,
+        feePercentage: feePercentage,
+    };
+}
+
+// 2: Create and start the gRPC server
+
+async function startServer() {
+    console.log('Starting gRPC Server...\n');
+
+    const server = await GrpcServerFactory.createServer(
+        {
+            packageName: 'calculator.v1',
+            serviceName: 'CalculatorService',
+            port: 50055,
+            protoOutputDir: path.join(__dirname, 'grpc'),
+        },
+        [
+            {
+                name: 'CalculateFee',
+                handler: calculateFee, // Your existing function!
+                requestSample: () => ({ merchantId: '', amount: 0, currency: '' }),
+                responseSample: () => ({
+                    originalAmount: 0,
+                    fee: 0,
+                    totalAmount: 0,
+                    currency: '',
+                    feePercentage: 0
+                }),
+            },
+        ]
+    );
+
+    await server.start();
+    return server;
+}
+
+// 3: Create a client and call the server
+
+async function callServer() {
+    console.log('\nCreating gRPC Client...\n');
+
+    // Wait a moment for server to be ready
+    await new Promise(resolve => setTimeout(resolve, 500));
+
+    const client = GrpcClientFactory.createClient<any>({
+        serviceName: 'CalculatorService',
+        packageName: 'calculator.v1',
+        protoPath: path.join(__dirname, 'grpc', 'calculator.proto'),
+        url: 'localhost:50055',
+    });
+
+    // Make a gRPC call
+    return new Promise<FeeResponse>((resolve, reject) => {
+        client.CalculateFee(
+            { merchantId: 'merchant_123', amount: 1000, currency: 'USD' },
+            (err: any, response: any) => {
+                if (err) {
+                    try {
+                        handleGrpcError(err);
+                    } catch (e) {
+                        reject(e);
+                    }
+                    return;
+                }
+                resolve(response);
+            }
+        );
+    });
+}
+
+// RUN THE DEMO
+async function main() {
+    console.log('------------------------------------------------------------');
+    console.log('  @themainstack/communication - Full gRPC Demo');
+    console.log('------------------------------------------------------------');
+    console.log('');
+
+    // Start server
+    const server = await startServer();
+
+    try {
+        // Call the server
+        const result = await callServer();
+
+        console.log('gRPC Call Successful!\n');
+        console.log('Request:  { merchantId: "merchant_123", amount: 1000, currency: "USD" }');
+        console.log('Response:', JSON.stringify(result, null, 2));
+        console.log('');
+    } catch (error) {
+        console.error('Error:', error);
+    } finally {
+        // Stop server
+        await server.stop();
+    }
+
+    console.log('------------------------------------------------------------');
+    console.log('  Demo Complete!');
+    console.log('------------------------------------------------------------');
+}
+
+main().catch(console.error);

package/examples/grpc/calculator.proto

@@ -0,0 +1,22 @@
+syntax = "proto3";
+
+package calculator.v1;
+
+// CalculatorService - Auto-generated gRPC service
+service CalculatorService {
+  rpc CalculateFee (CalculateFeeRequest) returns (CalculateFeeResponse) {}
+}
+
+message CalculateFeeResponse {
+  int32 original_amount = 1;
+  int32 fee = 2;
+  int32 total_amount = 3;
+  string currency = 4;
+  int32 fee_percentage = 5;
+}
+
+message CalculateFeeRequest {
+  string merchant_id = 1;
+  int32 amount = 2;
+  string currency = 3;
+}

package/examples/grpc/fee.proto

@@ -0,0 +1,60 @@
+syntax = "proto3";
+
+package fee.v1;
+
+// FeeService - Auto-generated gRPC service
+service FeeService {
+  rpc CalculateWithdrawalFee (CalculateWithdrawalFeeRequest) returns (CalculateWithdrawalFeeResponse) {}
+}
+
+message CalculateWithdrawalFeeResponse {
+  double dollar_amount = 1;
+  double dollar_transaction_fee = 2;
+  int32 local_transaction_fee = 3;
+  string local_currency = 4;
+  string local_amount = 5;
+  double exchange_rate = 6;
+  repeated AppliedFee applied_fees = 7;
+  repeated string applied_fee_ids = 8;
+  Tax tax = 9;
+}
+
+message Tax {
+  string id = 1;
+  double dollar_tax = 2;
+  int32 local_tax = 3;
+  int32 gateway_recorded_tax = 4;
+  int32 surplus_on_gateway_recorded_tax = 5;
+  repeated Breakdown breakdown = 6;
+}
+
+message Breakdown {
+  string country = 1;
+  int32 flat_amount = 2;
+  string percentage_decimal = 3;
+  string rate_type = 4;
+  string state = 5;
+  string tax_type = 6;
+  string taxability_reason = 7;
+}
+
+message AppliedFee {
+  string id = 1;
+  string type = 2;
+  string display_name = 3;
+  double amount = 4;
+  string amount_type = 5;
+  int32 extra = 6;
+  double value = 7;
+  double value_usd = 8;
+  bool is_mainstack = 9;
+  bool is_processor = 10;
+  bool is_deposit = 11;
+}
+
+message CalculateWithdrawalFeeRequest {
+  string merchant_id = 1;
+  double amount = 2;
+  string currency = 3;
+  string payout_method = 4;
+}

package/examples/protos/hero.proto

@@ -0,0 +1,17 @@
+syntax = "proto3";
+
+package hero.v1;
+
+service HeroService {
+  rpc GetHero (HeroRequest) returns (HeroResponse) {}
+}
+
+message HeroRequest {
+  int32 id = 1;
+}
+
+message HeroResponse {
+  int32 id = 1;
+  string name = 2;
+  string power = 3;
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+    "name": "@themainstack/communication",
+    "version": "1.0.0",
+    "private": false,
+    "description": "Unified gRPC framework for inter-service communication - auto-generates protos, creates servers, and provides type-safe clients",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "scripts": {
+        "build": "tsc -p tsconfig.json",
+        "prepublishOnly": "npm run build",
+        "test": "npx vitest --run"
+    },
+    "author": "Mainstack Engineering",
+    "license": "MIT",
+    "devDependencies": {
+        "typescript": "^5.3.3",
+        "vitest": "^4.0.7"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "dependencies": {
+        "@grpc/grpc-js": "^1.14.3",
+        "@grpc/proto-loader": "^0.8.0"
+    }
+}

package/src/grpc/client-factory.ts

@@ -0,0 +1,48 @@
+import * as grpc from '@grpc/grpc-js';
+import * as protoLoader from '@grpc/proto-loader';
+import { GrpcClientOptions } from './types';
+
+export class GrpcClientFactory {
+    static createClient<T extends grpc.Client>(options: GrpcClientOptions): T {
+        const packageDefinition = protoLoader.loadSync(options.protoPath, {
+            keepCase: true,
+            longs: String,
+            enums: String,
+            defaults: true,
+            oneofs: true,
+            ...options.loaderOptions,
+        });
+
+        const protoDescriptor = grpc.loadPackageDefinition(packageDefinition);
+
+        let serviceDef: any = protoDescriptor;
+
+        // Default to empty string (root) if not provided
+        const packageName = options.packageName || '';
+
+        // Only traverse if packageName is non-empty
+        if (packageName) {
+            const pkgNameParts = packageName.split('.');
+            for (const part of pkgNameParts) {
+                if (serviceDef[part]) {
+                    serviceDef = serviceDef[part];
+                } else {
+                    throw new Error(`Package part '${part}' not found in proto definition`);
+                }
+            }
+        }
+
+        if (!serviceDef[options.serviceName]) {
+            const location = packageName ? `package '${packageName}'` : 'root definition';
+            throw new Error(`Service '${options.serviceName}' not found in ${location}`);
+        }
+
+        const ServiceClient = serviceDef[options.serviceName];
+
+        return new ServiceClient(
+            options.url,
+            options.credentials || grpc.credentials.createInsecure(),
+            options.channelOptions
+        ) as T;
+    }
+}

package/src/grpc/errors.ts

@@ -0,0 +1,31 @@
+import { ServiceError, status } from '@grpc/grpc-js';
+
+export class GrpcError extends Error {
+    public code: status;
+    public details: string;
+    public metadata: any;
+
+    constructor(code: status, message: string, details?: string, metadata?: any) {
+        super(message);
+        this.name = 'GrpcError';
+        this.code = code;
+        this.details = details || message;
+        this.metadata = metadata;
+    }
+}
+
+export const handleGrpcError = (err: any): never => {
+    if (err && (err.code !== undefined || err.message)) {
+        const error = err as ServiceError;
+        // Map gRPC status codes to more friendly errors if needed
+        // For now, we wrap it in our GrpcError
+        throw new GrpcError(
+            error.code ?? status.UNKNOWN,
+            error.message || 'Unknown gRPC error',
+            error.details,
+            error.metadata
+        );
+    }
+
+    throw new GrpcError(status.UNKNOWN, 'An unexpected error occurred', JSON.stringify(err));
+};