@themainstack/communication 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,194 @@
+# @themainstack/communication
+
+A unified gRPC framework for inter-service communication at Mainstack.
+
+## Table of Contents
+1. [Overview](#overview)
+2. [Installation](#installation)
+3. [Proto Generation](#proto-generation)
+4. [Creating a gRPC Server](#creating-a-grpc-server)
+5. [Creating a gRPC Client](#creating-a-grpc-client)
+6. [Error Handling](#error-handling)
+7. [Full Example](#full-example)
+
+---
+
+## Overview
+
+The workflow is simple:
+
+```
+Developer writes TypeScript function
+         ↓
+Package auto-generates .proto file
+         ↓
+Server Factory exposes function as gRPC
+         ↓
+Client Factory in another service calls it
+         ↓
+Error Handler normalizes any errors
+```
+
+---
+
+## Installation
+
+```bash
+npm install @themainstack/communication
+# or
+yarn add @themainstack/communication
+```
+
+---
+
+## Proto Generation
+
+Auto-generate `.proto` files from your TypeScript types.
+
+```typescript
+import { generateProtoFromMethods } from '@themainstack/communication';
+
+generateProtoFromMethods([
+  {
+    name: 'CalculateFee',
+    requestSample: () => ({ merchantId: '', amount: 0, currency: '' }),
+    responseSample: () => ({ fee: 0, total: 0 }),
+  }
+], {
+  packageName: 'fee.v1',
+  serviceName: 'FeeService',
+  outputDir: './src/grpc',
+});
+```
+
+**Output:** `./src/grpc/feeservice.proto` is auto-generated!
+
+---
+
+## Creating a gRPC Server
+
+Expose existing functions as gRPC endpoints.
+
+```typescript
+import { GrpcServerFactory } from '@themainstack/communication';
+
+// Your existing business function
+async function calculateFee(request) {
+  return { fee: request.amount * 0.02, total: request.amount * 1.02 };
+}
+
+// Create and start the server
+const server = await GrpcServerFactory.createServer({
+  packageName: 'fee.v1',
+  serviceName: 'FeeService',
+  port: 50053,
+}, [
+  {
+    name: 'CalculateFee',
+    handler: calculateFee,  // Your existing function!
+    requestSample: () => ({ merchantId: '', amount: 0, currency: '' }),
+    responseSample: () => ({ fee: 0, total: 0 }),
+  }
+]);
+
+await server.start();
+// 🚀 gRPC Server running on 0.0.0.0:50053
+```
+
+### Quick Expose (One-liner)
+
+```typescript
+import { exposeAsGrpc } from '@themainstack/communication';
+
+const server = await exposeAsGrpc(
+  'CalculateFee',
+  calculateFee,
+  { requestSample: () => ({...}), responseSample: () => ({...}) },
+  { packageName: 'fee.v1', serviceName: 'FeeService', port: 50053 }
+);
+```
+
+---
+
+## Creating a gRPC Client
+
+Call gRPC services from other services.
+
+```typescript
+import { GrpcClientFactory } from '@themainstack/communication';
+
+const client = GrpcClientFactory.createClient({
+  serviceName: 'FeeService',
+  packageName: 'fee.v1',
+  protoPath: './src/grpc/fee.proto',
+  url: process.env.FEE_SERVICE_URL || 'localhost:50053',
+});
+
+// Make a call
+client.CalculateFee(
+  { merchantId: 'merchant_123', amount: 1000, currency: 'USD' },
+  (err, response) => {
+    if (err) {
+      handleGrpcError(err);
+      return;
+    }
+    console.log('Fee:', response.fee);
+  }
+);
+```
+
+---
+
+## Error Handling
+
+Standardized gRPC error translation.
+
+```typescript
+import { handleGrpcError } from '@themainstack/communication';
+
+client.SomeMethod(request, (err, response) => {
+  if (err) {
+    try {
+      handleGrpcError(err); // Throws normalized error
+    } catch (normalizedError) {
+      console.error(normalizedError.message);
+      // Handle based on error type
+    }
+    return;
+  }
+  // Process response
+});
+```
+
+---
+
+## Full Example
+
+See `examples/full-grpc-demo.ts` in the repository for a complete working example.
+
+---
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `GRPC_PORT` | Port for gRPC server | `50051` |
+| `FEE_SERVICE_URL` | Fee service gRPC address | `localhost:50053` |
+
+---
+
+## API Reference
+
+### Proto Generation
+- `generateProtoFromMethods(methods, options)` - Generate proto with service definition
+- `generateProtoFromFunction(fn, name)` - Generate proto for a single message
+
+### Server
+- `GrpcServerFactory.createServer(options, handlers)` - Create a gRPC server
+- `exposeAsGrpc(name, handler, samples, options)` - Quick one-liner
+
+### Client
+- `GrpcClientFactory.createClient(options)` - Create a gRPC client
+
+### Error Handling
+- `handleGrpcError(err)` - Translate gRPC errors to application errors

package/dist/proto-generator/index.js

@@ -89,7 +89,8 @@ function generateProtoFromMethods(methods, options = {}) {
                 if (value.length > 0) {
                     const firstItem = value[0];
                     if (typeof firstItem === "object") {
-                        const nestedName = capitalize(key).replace(/s$/, "");
+                        // Scope nested naming: Parent_Child
+                        const nestedName = `${msgName}_${capitalize(key).replace(/s$/, "")}`;
                         type = analyzeMessage(firstItem, nestedName);
                     }
                     else {
@@ -103,7 +104,8 @@ function generateProtoFromMethods(methods, options = {}) {
                 }
             }
             else if (valueType === "object") {
-                const nestedName = capitalize(key);
+                // Scope nested naming: Parent_Child
+                const nestedName = `${msgName}_${capitalize(key)}`;
                 type = analyzeMessage(value, nestedName);
             }
             // Use snake_case for proto fields

package/docs/INTEGRATION_EXAMPLE.md

@@ -127,6 +127,69 @@ export async function startGrpcServer() {
 }
 ```
 
+### 1.3.1 Organizing Handlers in Separate Files (Recommended)
+
+For services with many gRPC methods, you can keep your code clean by defining handlers in separate files and importing them:
+
+**Step 1: Define handlers in separate files**
+
+```typescript
+// fee-service/src/grpc/handlers/withdrawal-fee.handler.ts
+import { FeesService } from '../../fee/fees.service';
+
+const feesService = new FeesService();
+
+export const withdrawalFeeHandler = {
+  name: 'CalculateWithdrawalFee',
+  handler: async (request: any) => {
+    const result = await feesService.calculateFeesForPlan(
+      'starter',
+      request.currency,
+      request.amount,
+      'withdrawal',
+    );
+    return { /* mapped response */ };
+  },
+  requestSample: () => ({ merchantId: '', amount: 0, currency: '' }),
+  responseSample: () => ({ dollarAmount: 0, fee: 0 }),
+};
+```
+
+```typescript
+// fee-service/src/grpc/handlers/deposit-fee.handler.ts
+export const depositFeeHandler = {
+  name: 'CalculateDepositFee',
+  handler: async (request: any) => { /* logic */ },
+  requestSample: () => ({ /* ... */ }),
+  responseSample: () => ({ /* ... */ }),
+};
+```
+
+**Step 2: Import and use them in your bootstrap file**
+
+```typescript
+// fee-service/src/grpc/grpc-bootstrap.ts
+import { GrpcServerFactory } from '@themainstack/communication';
+import { withdrawalFeeHandler } from './handlers/withdrawal-fee.handler';
+import { depositFeeHandler } from './handlers/deposit-fee.handler';
+
+export async function startGrpcServer() {
+  const server = await GrpcServerFactory.createServer({
+    packageName: 'fee.v1',
+    serviceName: 'FeeService',
+    port: parseInt(process.env.GRPC_PORT || '50053'),
+  }, [
+    withdrawalFeeHandler,  // Clean imports!
+    depositFeeHandler,
+  ]);
+
+  await server.start();
+  return server;
+}
+```
+
+This keeps your bootstrap file as a simple **configuration list** while the actual business logic lives in dedicated handler files.
+
 ### 1.4 Integrate with main.ts
 
 ```typescript

package/examples/full-grpc-demo.ts

@@ -47,8 +47,8 @@ async function startServer() {
 
     const server = await GrpcServerFactory.createServer(
         {
-            packageName: 'calculator.v1',
-            serviceName: 'CalculatorService',
+            packageName: 'fee.v1',
+            serviceName: 'FeeService',
             port: 50055,
             protoOutputDir: path.join(__dirname, 'grpc'),
         },
@@ -58,11 +58,11 @@ async function startServer() {
                 handler: calculateFee, // Your existing function!
                 requestSample: () => ({ merchantId: '', amount: 0, currency: '' }),
                 responseSample: () => ({
-                    originalAmount: 0,
-                    fee: 0,
+                    originalAmount: 100,
+                    fee: 10,
                     totalAmount: 0,
-                    currency: '',
-                    feePercentage: 0
+                    currency: 'USD',
+                    feePercentage: 10
                 }),
             },
         ]
@@ -81,8 +81,8 @@ async function callServer() {
     await new Promise(resolve => setTimeout(resolve, 500));
 
     const client = GrpcClientFactory.createClient<any>({
-        serviceName: 'CalculatorService',
-        packageName: 'calculator.v1',
+        serviceName: 'FeeService',
+        packageName: 'fee.v1',
         protoPath: path.join(__dirname, 'grpc', 'calculator.proto'),
         url: 'localhost:50055',
     });
@@ -108,11 +108,6 @@ async function callServer() {
 
 // 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();
 
@@ -130,10 +125,6 @@ async function main() {
         // Stop server
         await server.stop();
     }
-
-    console.log('------------------------------------------------------------');
-    console.log('  Demo Complete!');
-    console.log('------------------------------------------------------------');
 }
 
 main().catch(console.error);

package/examples/grpc/fee.proto

@@ -4,57 +4,19 @@ package fee.v1;
 
 // FeeService - Auto-generated gRPC service
 service FeeService {
-  rpc CalculateWithdrawalFee (CalculateWithdrawalFeeRequest) returns (CalculateWithdrawalFeeResponse) {}
+  rpc CalculateFee (CalculateFeeRequest) returns (CalculateFeeResponse) {}
 }
 
-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 CalculateFeeResponse {
+  int32 original_amount = 1;
+  int32 fee = 2;
+  int32 total_amount = 3;
+  string currency = 4;
+  int32 fee_percentage = 5;
 }
 
-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 {
+message CalculateFeeRequest {
   string merchant_id = 1;
-  double amount = 2;
+  int32 amount = 2;
   string currency = 3;
-  string payout_method = 4;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@themainstack/communication",
-    "version": "1.0.0",
+    "version": "1.0.2",
     "private": false,
     "description": "Unified gRPC framework for inter-service communication - auto-generates protos, creates servers, and provides type-safe clients",
     "main": "dist/index.js",
@@ -23,4 +23,4 @@
         "@grpc/grpc-js": "^1.14.3",
         "@grpc/proto-loader": "^0.8.0"
     }
-}
+}

package/publish-config.npmrc

@@ -0,0 +1 @@
+//registry.npmjs.org/:_authToken=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

package/src/grpc/server-factory.ts

@@ -177,7 +177,7 @@ export class GrpcServerFactory {
             this.server.bindAsync(
                 address,
                 grpc.ServerCredentials.createInsecure(),
-                (error, port) => {
+                (error: Error | null, port: number) => {
                     if (error) {
                         reject(error);
                         return;

package/src/proto-generator/index.ts

@@ -109,7 +109,8 @@ export function generateProtoFromMethods(
                 if (value.length > 0) {
                     const firstItem = value[0];
                     if (typeof firstItem === "object") {
-                        const nestedName = capitalize(key).replace(/s$/, "");
+                        // Scope nested naming: Parent_Child
+                        const nestedName = `${msgName}_${capitalize(key).replace(/s$/, "")}`;
                         type = analyzeMessage(firstItem, nestedName);
                     } else {
                         type = typeof firstItem === "number"
@@ -120,7 +121,8 @@ export function generateProtoFromMethods(
                     type = "string";
                 }
             } else if (valueType === "object") {
-                const nestedName = capitalize(key);
+                // Scope nested naming: Parent_Child
+                const nestedName = `${msgName}_${capitalize(key)}`;
                 type = analyzeMessage(value, nestedName);
             }