@themainstack/communication 1.0.0 → 1.0.1

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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@themainstack/communication",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "private": false,
     "description": "Unified gRPC framework for inter-service communication - auto-generates protos, creates servers, and provides type-safe clients",
     "main": "dist/index.js",