open-index/open-npm huggingface dataset:
npm package: @rjrcosta/contracts
Description: Shared event contracts for SF microservices
Latest version: 1.0.4

# @sf/contracts

This package contains **immutable contracts** used for communication
between SF microservices.

## Rules
- Events are versioned (v1, v2, ...)
- Existing versions MUST NEVER change
- New changes require a new version

## Contents
- Events
- Commands (optional)
- Schemas

# Install in Microservices
npm i git+https://github.com/rjrcosta/sf-contracts.git#V1.0.1
npm package: @rjrcosta/messaging-rabbit
Description: Shared event contracts for SF microservices
Latest version: 1.0.0

# sf-messaging-rabbit

## Environment

Create a `.env` file (or copy `.env.example`) with:

- `SF_MQ_URL` (default: `amqp://guest:guest@localhost:5672`)
- `SF_MQ_EXCHANGE` (default: `sf.events`)
- `SF_MQ_PREFETCH` (default: `10`)
- `SF_MQ_RETRY_DELAY_MS` (default: `5000`)
- `SF_MQ_MAX_RETRIES` (default: `5`)

## Local RabbitMQ

```bash
docker compose -f docker-compose.yaml up -d
```

## Quick Usage

```ts
import { buildEvent, connectRabbit, createChannel, publish, subscribe } from 'sf-messaging-rabbit'

const exchange = 'sf.events'
const routingKey = 'customers.customer.created.v1'
const url = process.env.SF_MQ_URL || 'amqp://guest:guest@localhost:5672'

const connection = await connectRabbit(url)
const channel = await createChannel(connection)

const event = buildEvent({
  type: routingKey,
  source: 'sf-customers',
  payload: { customerId: '123', email: 'user@example.com' },
})

await publish(channel, exchange, routingKey, event)

await subscribe({
  channel,
  exchange,
  queue: 'sf-analytics.customers.created',
  routingKey,
  maxRetries: 5,
  retryDelayMs: 5000,
  onMessage: async (message) => {
    console.log('received', message)
  },
})
```

## Event Rules

✔ Eventos são imutáveis  
✔ Alterações = novo evento (v2, v3, …)  
✔ Nunca alterar ficheiros .v1  
✔ Backward compatibility obrigatória  
✔ Um serviço publica apenas eventos do seu domínio  
✔ Consumers devem ser tolerantes a versões antigas  
✔ DLQ obrigatória para todos os consumers  
✔ Retry sempre controlado (nunca infinito)

“E se o Rabbit estiver em baixo quando o Orders cria uma order?”

A resposta envolve:

outbox pattern
retries
idempotência

┌────────────────────────────┐
│ Microserviço (Node.js)     │
│                            │
│  - orders                  │
│  - customers               │
│  - analytics               │
│                            │
│  imports                    │
│   ├─ @sf/contracts   (npm) │
│   └─ @sf/messaging-* (npm) │
│                            │
└──────────────┬─────────────┘
               │ AMQP / Kafka protocol
               ▼
        ┌─────────────┐
        │ RabbitMQ    │  ← servidor externo
        └─────────────┘

# Naming Convention
    <domain>.<entity>.<action>.<version>

    Exemplos
    orders.order.created.v1
    catalog.product.price-updated.v1
    customers.customer.created.v1