@delpa/delpa-back-protos

Definiciones Protocol Buffers compartidas para los microservicios de Delpa.

Instalación

pnpm add @delpa/delpa-back-protos
# o
npm install @delpa/delpa-back-protos

Uso

Importar tipos y definiciones de servicio

import {
  // Health service
  HealthServiceDefinition,
  HealthCheckRequest,
  HealthCheckResponse,
  
  // Carriers service
  CarrierServiceDefinition,
  Carrier,
  CreateCarrierRequest,
  
  // Rates service
  ExternalRateServiceDefinition,
  QuoteRequest,
  QuoteResponse,
} from '@delpa/delpa-back-protos';

Importar namespaces completos

import { healthv1, carriersv1, ratesv1 } from '@delpa/delpa-back-protos';

// Usar tipos específicos
const request: healthv1.HealthCheckRequest = {
  service: 'my-service'
};

Importar servicios específicos

import { HealthServiceDefinition } from '@delpa/delpa-back-protos/health';
import { CarrierServiceDefinition } from '@delpa/delpa-back-protos/carriers';
import { ExternalRateServiceDefinition } from '@delpa/delpa-back-protos/rates';

Servicios disponibles

Health Service

• HealthService.Check - Verificar estado del servicio
• HealthService.Watch - Stream de estado del servicio
• DetailedHealthService.DetailedCheck - Verificación detallada

Carriers Service

• CarrierService.CreateCarrier - Crear transportista
• CarrierService.GetCarrier - Obtener transportista por ID
• CarrierService.GetCarrierByCode - Obtener transportista por código
• CarrierService.GetCarriers - Listar transportistas
• CarrierService.UpdateCarrier - Actualizar transportista
• CarrierService.DeleteCarrier - Eliminar transportista
• CarrierService.EnableCarrier - Habilitar transportista
• CarrierService.DisableCarrier - Deshabilitar transportista

Rates Service

• ExternalRateService.GetQuotes - Obtener cotizaciones
• ExternalRateService.GetCachedRates - Obtener tarifas cacheadas
• ExternalRateService.GetCarriersStatus - Estado de transportistas
• ProfitRuleService.* - Gestión de reglas de ganancia

Desarrollo

# Generar código TypeScript desde protos
pnpm gen

# Build completo
pnpm build

# Limpiar archivos generados
pnpm clean

Estructura

├── protos/
│   ├── health/v1/health.proto
│   ├── carriers/v1/carriers.proto
│   └── rates/v1/rates.proto
├── generated/         # Código TS generado (ignorado en git)
├── dist/              # Build final (ignorado en git)
└── index.ts           # Punto de entrada

Agregar un nuevo archivo Proto

Para agregar un nuevo servicio proto, sigue estos pasos:

1. Crear el archivo .proto

Crea el archivo en la estructura protos/<servicio>/v1/<servicio>.proto:

mkdir -p protos/orders/v1
touch protos/orders/v1/orders.proto

2. Definir el servicio

syntax = "proto3";

package orders;

service OrderService {
  rpc CreateOrder(CreateOrderRequest) returns (Order);
  rpc GetOrder(GetOrderRequest) returns (Order);
}

message Order {
  string id = 1;
  string status = 2;
  string createdAt = 3;
}

message CreateOrderRequest {
  string customerId = 1;
  repeated string items = 2;
}

message GetOrderRequest {
  string id = 1;
}

3. Agregar al script de generación

Edita package.json y agrega el nuevo proto al script gen:

{
  "scripts": {
    "gen": "mkdir -p generated && protoc ... protos/orders/v1/orders.proto"
  }
}

4. Exportar en index.ts

Edita index.ts y agrega los exports del nuevo servicio:

// Orders service
export * as ordersv1 from "./generated/orders/v1/orders";
export { OrderServiceDefinition } from "./generated/orders/v1/orders";
export type {
  Order,
  CreateOrderRequest,
  GetOrderRequest,
} from "./generated/orders/v1/orders";

5. Agregar export en package.json

Agrega el nuevo path en la sección exports de package.json:

{
  "exports": {
    "./orders": {
      "types": "./dist/generated/orders/v1/orders.d.ts",
      "import": "./dist/generated/orders/v1/orders.js"
    }
  }
}

6. Generar y probar

# Generar código TypeScript
pnpm gen

# Compilar
pnpm build

# Verificar que no hay errores

7. Publicar nueva versión

# Incrementar versión (patch, minor o major según el cambio)
npm version patch

# Publicar
npm publish --access public

Convenciones

• Versionado: Usar estructura v1, v2 para versionado de API
• Nombres: Usar PascalCase para mensajes y servicios, camelCase para campos
• Package: El package debe coincidir con el nombre del servicio (ej: package orders;)
• Enums: Primer valor debe ser UNSPECIFIED = 0