npm package: @onlineapps/conn-orch-registry
Description: Connector-registry-client provides the core communication mechanism for microservices in this environment. It enables them to interact with a services_registry to receive and fulfill tasks by submitting heartbeats or their API descriptions.
Latest version: 1.1.54

# @onlineapps/conn-orch-registry

[![Build Status](https://img.shields.io/github/actions/workflow/status/onlineapps/conn-orch-registry/nodejs.yml?branch=main)](https://github.com/onlineapps/conn-orch-registry/actions)
[![Coverage Status](https://codecov.io/gh/onlineapps/conn-orch-registry/branch/main/graph/badge.svg)](https://codecov.io/gh/onlineapps/conn-orch-registry)
[![npm version](https://img.shields.io/npm/v/@onlineapps/conn-orch-registry)](https://www.npmjs.com/package/@onlineapps/conn-orch-registry)

> A lightweight client for microservice registration, heartbeat, and API description exchange via RabbitMQ.

## 🚀 Features

* Automatic queue management (`workflow`, `<serviceName>.registry`, `api_services_queuer`, `registry.register`)
* Periodic heartbeat messages with metadata
* API description request/response flow
* Event-driven API using `EventEmitter`
* Fully configurable via environment variables or constructor options

## 📦 Installation

```bash
npm install @onlineapps/conn-orch-registry
# or
yarn add @onlineapps/conn-orch-registry
```

## 🔧 Quick Start

```js
// NOTE: Do NOT call dotenv.config() in libraries. Export environment variables explicitly.

const { ServiceRegistryClient, EVENTS } = require('@onlineapps/conn-orch-registry');

const client = new ServiceRegistryClient({
  amqpUrl: process.env.AMQP_URL,
  serviceName: 'invoicing',
  version: '1.0.0'
});

// Listen for API description requests
client.on(EVENTS.API_DESCRIPTION_REQUEST, async () => {
  const apiSpec = await loadOpenApiSpec();
  await client.sendApiDescription(apiSpec);
});

// Initialize and start heartbeats
await client.init();
client.startHeartbeat();

// Graceful shutdown
process.on('SIGINT', async () => {
  await client.close();
  process.exit(0);
});
```

## 📄 Configuration

Configuration can be provided via environment variables or constructor options:

| Variable             | Description                                   | Default              |
| -------------------- | --------------------------------------------- | -------------------- |
| `AMQP_URL`           | RabbitMQ connection string (required)         | —                    |
| `SERVICE_NAME`       | Logical name of your service (required)       | —                    |
| `SERVICE_VERSION`    | Service version in SemVer format (required)   | —                    |
| `HEARTBEAT_INTERVAL` | Interval in ms between heartbeats             | `10000`              |
| `API_QUEUE`          | Queue name for heartbeat/API messages         | `api_services_queuer` |
| `REGISTRY_QUEUE`     | Queue name for registry requests/descriptions | `registry.register`  |

## 📨 Message Formats

### Register Request
```javascript
{
  type: "register",
  serviceName: "hello-service",
  version: "1.0.0",
  token: "pre-validation-token",
  endpoints: [...],
  timestamp: "ISO-8601"
}
```

### Register Confirmed
```javascript
{
  type: "register.confirmed",
  serviceName: "hello-service",
  success: true,
  certificate: {
    id: "cert-uuid",
    signature: "cryptographic-signature",
    validUntil: "ISO-8601"
  },
  cached: false
}
```

### Heartbeat
```javascript
{
  type: "heartbeat",
  serviceName: "hello-service",
  status: "UP",
  timestamp: "ISO-8601"
}
```

## 🛠️ API Reference

See [docs/api.md](https://github.com/onlineapps/conn-orch-registry/blob/main/docs/api.md) for full details on classes, methods, and events.

## 📖 Documentation

* Architecture overview: [docs/architecture.md](https://github.com/onlineapps/conn-orch-registry/blob/main/docs/architecture.md)
* API reference: [docs/api.md](https://github.com/onlineapps/conn-orch-registry/blob/main/docs/api.md)
* Examples: [examples/basicUsage.js](https://github.com/onlineapps/agent-registry-client/blob/main/examples/basicUsage.js)

## 🔗 Related Documentation

- **[⭐ Complete Two-Tier Validation System](/docs/modules/validator.md)** - Full validation architecture and flow
- [Registry Module Overview](/docs/modules/registry.md) - High-level registry system architecture
- [api_services_registry](/api/api_services_registry/README.md) - Registry service implementation

## ✅ Testing

```bash
# Run unit and integration tests
yarn test
# or
npm test
```

## 🎨 Coding Standards

* **Linting**: ESLint (Airbnb style)
* **Formatting**: Prettier
* **Testing**: Jest

## 🤝 Contributing

Please read [CONTRIBUTING.md](https://github.com/onlineapps/agent-registry-client/blob/main/CONTRIBUTING.md) for details on submitting issues and pull requests.

## 📜 License

This project is licensed under the MIT License. See [LICENSE](https://github.com/onlineapps/agent-registry-client/blob/main/LICENSE) for details.

## 📚 Documentation

- [Complete Connectors Documentation](../../../docs/modules/connector.md)
- [Testing Standards](../../../docs/modules/connector.md#testing-standards)