@axxel/event-bus 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +168 -0
  2. package/package.json +38 -0
package/README.md ADDED
@@ -0,0 +1,168 @@
1
+ # @axxel/event-bus
2
+
3
+ A lightweight SDK for producing and consuming real-time events via **Amazon MSK (Kafka)** for the Axxel ecosystem.
4
+
5
+ This library provides a simple TypeScript interface for publishing and subscribing to:
6
+
7
+ - `token-prices` — token price updates across multiple chains
8
+ - `wallet-transactions` — wallet buy/sell/transfer activity
9
+
10
+ ---
11
+
12
+ ## 🚀 Installation
13
+
14
+ ```bash
15
+ npm install @axxel/event-bus
16
+ # or
17
+ yarn add @axxel/event-bus
18
+ ```
19
+
20
+ ---
21
+
22
+ ## ⚙️ Setup
23
+
24
+ Make sure your environment variables point to your Kafka (MSK) cluster:
25
+
26
+ ```bash
27
+ KAFKA_BROKER="b-1.mskcluster.amazonaws.com:9094,b-2.mskcluster.amazonaws.com:9094"
28
+ ```
29
+
30
+ If using local Kafka (for testing):
31
+
32
+ ```bash
33
+ KAFKA_BROKER="localhost:9092"
34
+ ```
35
+
36
+ ---
37
+
38
+ ## 🔌 Quick Start
39
+
40
+ ### 1️⃣ Producing messages
41
+
42
+ ```ts
43
+ import { produceTokenPrice, produceWalletTransaction } from '@axxel/event-bus';
44
+
45
+ await produceTokenPrice({
46
+ chain: 'ETH',
47
+ token: '0xC02a...',
48
+ symbol: 'WETH',
49
+ price: 3250.42,
50
+ timestamp: Date.now(),
51
+ });
52
+
53
+ await produceWalletTransaction({
54
+ chain: 'BASE',
55
+ wallet: '0xabc...',
56
+ token: '0x123...',
57
+ action: 'BUY',
58
+ amount: 10.5,
59
+ txHash: '0xdeadbeef...',
60
+ timestamp: Date.now(),
61
+ });
62
+ ```
63
+
64
+ ---
65
+
66
+ ### 2️⃣ Consuming messages
67
+
68
+ ```ts
69
+ import {
70
+ startTokenPriceConsumer,
71
+ startWalletTransactionConsumer,
72
+ } from '@axxel/event-bus';
73
+
74
+ await startTokenPriceConsumer('limit-orders', async (priceEvent) => {
75
+ console.log(`📈 ${priceEvent.symbol} @ $${priceEvent.price}`);
76
+ });
77
+
78
+ await startWalletTransactionConsumer('wallet-tracker', async (txEvent) => {
79
+ console.log(
80
+ `💸 ${txEvent.wallet} ${txEvent.action} ${txEvent.amount} ${txEvent.token}`,
81
+ );
82
+ });
83
+ ```
84
+
85
+ Each service should use a unique **consumer group ID** (`limit-orders`, `wallet-tracker`, `ai-engine`, etc.)
86
+ Multiple instances with the same group ID will automatically load-balance partitions.
87
+
88
+ ---
89
+
90
+ ## 🧠 Topics Overview
91
+
92
+ | Topic | Description | Partition Key |
93
+ | --------------------- | ------------------------------------------ | -------------- |
94
+ | `token-prices` | Live token price updates across all chains | `chain:token` |
95
+ | `wallet-transactions` | Wallet buy/sell/transfer events | `chain:wallet` |
96
+
97
+ ---
98
+
99
+ ## 🧱 Message Schemas
100
+
101
+ ### TokenPriceEvent
102
+
103
+ ```ts
104
+ interface TokenPriceEvent {
105
+ chain: string;
106
+ token: string;
107
+ symbol: string;
108
+ price: number;
109
+ timestamp: number;
110
+ }
111
+ ```
112
+
113
+ ### WalletTransactionEvent
114
+
115
+ ```ts
116
+ interface WalletTransactionEvent {
117
+ chain: string;
118
+ wallet: string;
119
+ token: string;
120
+ action: 'BUY' | 'SELL' | 'TRANSFER';
121
+ amount: number;
122
+ txHash: string;
123
+ timestamp: number;
124
+ }
125
+ ```
126
+
127
+ ---
128
+
129
+ ## ⚙️ Environment Variables
130
+
131
+ | Variable | Description | Example |
132
+ | --------------------- | ------------------------------------- | ------------------ |
133
+ | `KAFKA_BROKER` | Comma-separated list of Kafka brokers | `"localhost:9092"` |
134
+ | `KAFKA_SSL` | Enable SSL (for MSK) | `"true"` |
135
+ | `KAFKA_SASL_USERNAME` | SASL username (if using auth) | `"user"` |
136
+ | `KAFKA_SASL_PASSWORD` | SASL password | `"pass"` |
137
+
138
+ ---
139
+
140
+ ## 🧩 Advanced Usage
141
+
142
+ You can also create your own consumers or producers using the exported `kafka` client:
143
+
144
+ ```ts
145
+ import { kafka } from '@axxel/event-bus';
146
+
147
+ const producer = kafka.producer();
148
+ await producer.connect();
149
+ // custom logic...
150
+ ```
151
+
152
+ ---
153
+
154
+ ## 🧭 Example Architecture
155
+
156
+ ```
157
+ Axxel Services
158
+ │
159
+ ├── Trading Bot → produce token-prices, wallet-transactions
160
+ ├── AI Engine → consume token-prices & wallet-transactions, produce ai-signals
161
+ └── Analytics → consume everything
162
+ ```
163
+
164
+ ---
165
+
166
+ ## 📄 License
167
+
168
+ MIT © Axxel
package/package.json ADDED
@@ -0,0 +1,38 @@
1
+ {
2
+ "name": "@axxel/event-bus",
3
+ "version": "1.0.0",
4
+ "description": "Axxel Kafka Event Bus SDK",
5
+ "main": "dist/index.js",
6
+ "types": "dist/index.d.ts",
7
+ "files": [
8
+ "dist"
9
+ ],
10
+ "publishConfig": {
11
+ "access": "public"
12
+ },
13
+ "scripts": {
14
+ "dev": "tsx example/demo.ts",
15
+ "build": "tsc",
16
+ "start": "node dist/index.js",
17
+ "lint": "eslint . --ext .ts",
18
+ "format": "prettier --write .",
19
+ "clean": "rm -rf dist",
20
+ "prepublishOnly": "npm run build",
21
+ "test": "echo \"No tests yet\" && exit 0",
22
+ "publish:public": "npm publish --access public",
23
+ "publish:private": "npm publish"
24
+ },
25
+ "keywords": [],
26
+ "author": "",
27
+ "license": "ISC",
28
+ "dependencies": {
29
+ "dotenv": "^17.2.3",
30
+ "kafkajs": "^2.2.4"
31
+ },
32
+ "devDependencies": {
33
+ "@types/node": "^24.9.2",
34
+ "ts-node": "^10.9.2",
35
+ "tsx": "^4.20.6",
36
+ "typescript": "^5.9.3"
37
+ }
38
+ }