npm package: @heliont/n8n-nodes-heliont-messaging-hub
Description: Heliont Messaging Hub node for n8n
Author: Mario Bitter
Latest version: 1.3.2

# Heliont Messaging Hub — n8n Custom Nodes

**A powerful messaging framework for n8n workflows, built for flexibility, interoperability, and flow-based contracts.**

![n8n](https://img.shields.io/badge/built%20for-n8n-orange?logo=n8n) ![npm](https://img.shields.io/npm/v/@heliont/n8n-nodes-messaging-hub) ![License](https://img.shields.io/npm/l/@heliont/n8n-nodes-messaging-hub)

## ✨ Overview

The **Heliont Messaging Hub** is a modular and extensible node suite for [n8n](https://n8n.io/) that provides:

- Contract-based data routing and transformation
- Seamless message handoff between workflows
- Multi-provider message normalization (Meta, Twilio, WhatsApp, etc.)
- Inbound and outbound messaging pipelines with queueing and database persistence

It is ideal for conversational platforms, chatbots, middleware, and data brokers that require structured message orchestration.

---

## 📦 Nodes Included

### 🧠 `Contract Generator`
Creates a **global contract object** that can be reused across the workflow or multiple workflows. Think of it as the shared schema / context for a conversation.

- Input: JSON contract definition
- Outputs:
  - Forwarded data (with `contract` key stripped)
  - Contract as a separate output
- Use at the start of a workflow

---

### 🛠️ `Contract Recalibrator`
Modifies the **in-memory contract object**.

- Add or update fields using dot notation (`botUser.name`)
- Remove fields from the contract dynamically
- Use case: enrich contract mid-flow (e.g., add resolved user ID)

---

### 📤 `Contract Provider`
Retrieves the current **global contract**.

- Forwards original data
- Outputs the current contract state
- Use case: inspect or fork contract logic elsewhere in the flow

---

### 🧬 `Contract Teleporter`
Teleports contract + input data to another workflow.

- Target workflow ID required
- Fire-and-forget or wait-for-completion modes
- Use case: modular microflows, decoupled worker logic

---

### 🧲 `Contract Rematerializer`
Restores contract + input data in a **receiving workflow**.

- Typically the first node in a target workflow receiving from `Contract Teleporter`
- Reinstates contract in memory
- Outputs:
  - Input items (cleaned)
  - Rehydrated contract

---

### 📥 `Heliont Messaging Receiver`
Receives and stores **inbound messages**.

- Parses raw messages using the contract's provider and version
- Stores normalized message into a database
- Outputs: `bot_message_type`, `bot_message_content`, and timestamp

---

### 📤 `Heliont Messaging Sender`
Creates, queues, and/or sends **outbound messages**.

- Uses contract data to build outbound messages
- Modes:
  - `createMessage`: Build but do not send
  - `sendQueue`: Send previously queued
  - `createAndSendQueue`: Build and send
  - `sendInstant`: Build and send immediately, no persistence
- Output: summary (`createdCount`, `sentCount`, etc.) + forwarded items

---

## 🧩 Contract Pattern

This package follows a **flow contract pattern**, where a JSON-based `contract` is initialized at the start and accessed across the workflow. This pattern:

- Decouples logic from implementation
- Enables cross-workflow context sharing
- Standardizes how messages are parsed, stored, and sent

Example contract keys:
```json
{
  "botSystem": {
    "provider": "meta",
    "api-version": "v22.0",
    "botId": "123456"
  },
  "botMessage": {
    "rawMessage": "{...}"
  },
  "botUser": {
    "id": "user-uuid",
    "name": "John Doe"
  }
}
```

---

## 🔗 Installation

1. Add to your n8n environment:

```bash
npm install @heliont/n8n-nodes-messaging-hub
```

2. Ensure your custom nodes directory is configured in `n8n`.

```env
N8N_CUSTOM_EXTENSIONS=/path/to/custom-nodes
```

3. Restart n8n:

```bash
n8n stop && n8n start
```

---

## 🛡️ Authentication

Some nodes require a **Heliont Messaging Hub Credential**, which typically includes database access information. Ensure this credential is created in the n8n UI under *Credentials > Heliont Messaging Hub*.

---

## 🛠️ Dependencies

- n8n >= 1.0.0
- Relies on global workflow memory (`getWorkflowStaticData('global')`)
- Compatible with structured messaging from platforms like Meta, Twilio, etc.

---

## 📚 Examples

- **Contract-first flow**: initialize → enrich → send
- **Cross-workflow**: contract + input → teleporter → rematerializer → receiver
- **Bot platform integration**: normalize inbound from Meta API → store → respond

---

## 🧠 Design Philosophy

This node suite is designed for **enterprise-grade conversation flows**, with:

- Modular, testable nodes
- Memory-safe contract operations
- Clean separation of routing vs business logic
- Support for both linear and branched flow architectures

---

## 📄 License

MIT License — see [`LICENSE`](./LICENSE)

---

## 💡 Author

Made with 💚 by [Heliont](https://www.heliont.com) — powering secure identity, messaging, and automation infrastructure.