Glow Events SDK

A TypeScript-first SDK for consuming and emitting typed events on the Glow platform, powered by RabbitMQ (topic exchange). Provides runtime validation and type inference using Zod schemas.

---

🚀 Quick Start

$3

``bash
pnpm install @glowlabs-org/events-sdk
`

---

📚 Zones

The following zones are currently available:

| Zone ID | Zone Name |
| ------- | ------------------ |
| 0 | All Zones |
| 1 | Clean Grid Project |
| 2 | Coming Soon Zone |

- Use zoneId: 0 (with zoneName: "All Zones") to listen to all zones. Emitters must be constructed with a specific zoneId (not 0).
- The SDK types and runtime validation now officially support zoneId: 0 and zoneName: "All Zones" everywhere for listeners, but not for emitters.
- Use the getZoneId utility to get the correct zoneId for a given zone name:

`ts
import { getZoneId } from "@glowlabs-org/events-sdk";
const zoneId = getZoneId("CleanGridProject");
`

---

🛠️ Options for Listeners & Emitters

Both createGlowEventListener and createGlowEventEmitter accept the following options:

| Option | Type | Required | Description |
| ---------------- | ------ | -------- | ------------------------------------------------------------------ |
| username | string | Yes | RabbitMQ username |
| password | string | Yes | RabbitMQ password |
| zoneId | number | Yes | Zone ID (use getZoneId("ZoneName")) |
| queueName | string | No | (Listener only) Pre-created queue name |
| exchangePrefix | string | No | Exchange prefix (default: glow.zone-) |
| host | string | No | RabbitMQ host/port (default: turntable.proxy.rlwy.net:50784) |

---

📦 Event Types & Versions

Currently supported event types and versions:

| Event Name | Version | Payload Type | Description |
| ------------------------- | ---------- | ------------------------------------- | --------------------------------------------------- |
| audit.pushed | "v1" | AuditPushedV1Payload | Emitted when an audit is pushed |
| audit.slashed | "v1" | AuditSlashedV1Payload | Emitted when a farm is slashed |
| audit.pfees.paid | "v1" | AuditPfeesPaidV1Payload | Paid (by applicationId) |
| audit.pfees.paid | "v2" | AuditPfeesPaidV2Payload | Paid (by farmId) |
| audit.pfees.paid | "v2-alpha" | AuditPfeesPaidV2AlphaPayload | Paid (by applicationId) + currency metadata |
| application.created | "v1" | ApplicationCreatedV1Payload | Emitted when an application is created |
| application.created | "v2-alpha" | ApplicationCreatedV2AlphaPayload | V2-alpha: adds protocol fee price, omits installer |
| audit.pushed | "v2" | AuditPushedV2Payload | Emitted when an audit is pushed (farmId is bytes16) |
| audit.pushed | "v2-alpha" | AuditPushedV2AlphaPayload | Same as v1 but without protocol fee |
| application.price.quote | "v2-alpha" | ApplicationPriceQuoteV2AlphaPayload | Price quote for application |
| gctl.minted | "v2-alpha" | GctlMintedV2AlphaPayload | GCTL minted amount and metadata |
| auditor.fees.paid | "v2-alpha" | AuditorFeesPaidV2AlphaPayload | Auditor fee paid (by applicationId) |
| fraction.created | "v2-alpha" | FractionCreatedV2AlphaPayload | Fraction created with token and ownership details |
| fraction.sold | "v2-alpha" | FractionSoldV2AlphaPayload | Fraction sold between creator and buyer |
| fraction.closed | "v2-alpha" | FractionClosedV2AlphaPayload | Fraction closed/cancelled |
| fraction.refunded | "v2-alpha" | FractionRefundedV2AlphaPayload | Fraction refunded to user |

> Environment: All events include an environment field that defaults to "production". You can set it to "staging" when creating an emitter.

---

$3

The SDK provides a TypeScript constant for all supported event types to ensure type safety and avoid typos:

`ts
import { eventTypes, EventType } from "./src/event-types";

// Usage example:
const myEventType: EventType = eventTypes.auditPushed;
`

- eventTypes is a readonly object containing all event type strings.
- EventType is a TypeScript type representing any valid event type string.

Use these in your code to avoid hardcoding event names and to benefit from autocompletion and type checking.

---

📝 Event Payload Schemas

$3

`ts
export interface AuditPushedV1Payload {
farmId: string; // UUID string
protocolFeeUSDPrice_6Decimals: string; // uint256 (decimal) − 12 implied decimals
expectedProduction_12Decimals: string; // uint256 (decimal) − 12 implied decimals
txHash: string; // bytes32 hex string (0x...)
}
`

Validation:

- farmId must be a valid UUID string (e.g., afbc56b6-0b16-4119-b144-025728067ba6).
- protocolFeeUSDPrice_6Decimals and expectedProduction_12Decimals must be decimal strings representing unsigned big integers.
- txHash must be a 32-byte hex string (e.g., 0x...).

$3

`ts
export interface AuditSlashedV1Payload {
farmId: string; // bytes16 hex string (0x...)
slasher: string; // Ethereum address (0x...)
txHash: string; // bytes32 hex string (0x...)
}
`

Validation:

- farmId must be a 16-byte hex string (e.g., 0x...).
- slasher must be a valid Ethereum address (0x...40 hex chars).
- txHash must be a 32-byte hex string (e.g., 0x...).

$3

`ts
export interface AuditPfeesPaidV1Payload {
applicationId: string; // UUID string
payer: string; // Ethereum address (0x...)
amount_6Decimals: string; // uint256 (decimal) − 6 implied decimals
txHash: string; // bytes32 hex string (0x...)
}
`

Validation:

- applicationId must be a valid UUID string (e.g., 3ed964b1-4f02-475a-9789-fb74b3466c70).
- payer must be a valid Ethereum address (0x...40 hex chars).
- amount_6Decimals must be a decimal string representing an unsigned big integer (6 implied decimals).
- txHash must be a 32-byte hex string (e.g., 0x...).

$3

`ts
export interface AuditPfeesPaidV2Payload {
farmId: string; // bytes16 hex string (0x...)
payer: string; // Ethereum address (0x...)
amount_12Decimals: string; // uint256 (decimal) − 12 implied decimals
txHash: string; // bytes32 hex string (0x...)
}
`

Validation:

- farmId must be a 16-byte hex string (e.g., 0x...).
- payer must be a valid Ethereum address (0x...40 hex chars).
- amount_12Decimals must be a decimal string representing an unsigned big integer (12 implied decimals).
- txHash must be a 32-byte hex string (e.g., 0x...).

$3

``ts
export interface AuditPushedV2Payload {
farmId: string; // bytes16 hex string (0x...)
protocolFeeUSDPrice_12Decimals: string; // uint256 (decimal) − 12 implied decimals
expectedProduction_12Decimals: string; // uint256 (decimal) − 12 implied decimals
txHash: string; // bytes32 hex string (0x...)
}

$3

`ts
export interface AuditPushedV2AlphaPayload {
farmId: string; // UUID string
expectedProduction_12Decimals: string; // uint256 (decimal) − 12 implied decimals
txHash: string; // bytes32 hex string (0x...)
}
``

$3

`ts
export type PaymentCurrency = "GCTL" | "USDC" | "USDG" | "GLW" | "SGCTL";
export interface AuditPfeesPaidV2AlphaPayload {
applicationId: string; // UUID string
payer: string; // Ethereum address (0x...)
amount_6Decimals: string; // uint256 (decimal) − 6 implied decimals
txHash: string; // bytes32 hex string (0x...)
paymentCurrency: PaymentCurrency;
paymentEventType: string;
isSponsored: boolean;
}
`

$3

`ts
export interface ApplicationPriceQuoteV2AlphaPayload {
applicationId: string; // UUID string
createdAt: string; // ISO-8601 datetime string
prices: { GCTL: string; GLW: string; USDC: string; USDG: string }; // uint256 decimal strings
signature: string; // bytes32 hex string (0x...)
gcaAddress: string; // Ethereum address (0x...)
}
`

$3

`ts
export interface GctlMintedV2AlphaPayload {
gctlAmount_6Decimals: string; // uint256 (decimal) − 6 implied decimals
timestamp: string; // ISO-8601 datetime string
minter: string; // Ethereum address (0x...)
txHash: string; // bytes32 hex string (0x...)
}
`

$3

`ts
export interface AuditorFeesPaidV2AlphaPayload {
applicationId: string; // UUID string
payer: string; // Ethereum address (0x...)
amount_6Decimals: string; // uint256 (decimal) − 6 implied decimals
txHash: string; // bytes32 hex string (0x...)
}
`

$3

`ts
export interface FractionCreatedV2AlphaPayload {
fractionId: string;
transactionHash: string; // bytes32 hex string (0x...)
blockNumber: string; // uint256 (decimal)
logIndex: number;
token: string; // Ethereum address (0x...)
owner: string; // Ethereum address (0x...)
step: string; // uint256 (decimal)
totalSteps: string; // uint256 (decimal)
}
`

$3

`ts
export interface FractionSoldV2AlphaPayload {
fractionId: string;
transactionHash: string; // bytes32 hex string (0x...)
blockNumber: string; // uint256 (decimal)
logIndex: number;
creator: string; // Ethereum address (0x...)
buyer: string; // Ethereum address (0x...)
step: string; // uint256 (decimal)
amount: string; // uint256 (decimal)
timestamp: number;
}
`

$3

`ts
export interface FractionClosedV2AlphaPayload {
fractionId: string;
transactionHash: string; // bytes32 hex string (0x...)
blockNumber: string; // uint256 (decimal)
logIndex: number;
token: string; // Ethereum address (0x...)
owner: string; // Ethereum address (0x...)
timestamp: number;
}
`

Validation:

- fractionId is a string identifier.
- transactionHash must be a 32-byte hex string.
- blockNumber, step, totalSteps, and amount must be decimal strings representing unsigned big integers.
- token, owner, creator, and buyer must be valid Ethereum addresses.

---

`ts
export interface FractionSoldV2AlphaPayload {
fractionId: string;
transactionHash: string; // bytes32 hex string (0x...)
blockNumber: string; // uint256 (decimal)
logIndex: number;
creator: string; // Ethereum address (0x...)
buyer: string; // Ethereum address (0x...)
step: string; // uint256 (decimal)
amount: string; // uint256 (decimal)
timestamp: number;
}
`

$3

`ts
export interface FractionClosedV2AlphaPayload {
fractionId: string;
transactionHash: string; // bytes32 hex string (0x...)
blockNumber: string; // uint256 (decimal)
logIndex: number;
token: string; // Ethereum address (0x...)
owner: string; // Ethereum address (0x...)
timestamp: number;
}
`

$3

`ts
export interface FractionRefundedV2AlphaPayload {
fractionId: string; // hex string
creator: string; // Ethereum address (0x...)
user: string; // Ethereum address (0x...)
refundTo: string; // Ethereum address (0x...)
amount: string; // uint256 (decimal)
timestamp: number;
blockNumber: string; // uint256 (decimal)
transactionHash: string; // bytes32 hex string (0x...)
logIndex: number;
}
`

---

$3

`ts
export interface ApplicationCreatedV2AlphaPayload {
gcaAddress: string; // Ethereum address (0x...)
lat: number;
lng: number;
estimatedCostOfPowerPerKWh: number;
estimatedKWhGeneratedPerYear: number;
estimatedProtocolFeeUSDPrice_6Decimals: string; // uint256 (decimal) − 6 implied decimals
}
`

Validation:

- gcaAddress must be a valid Ethereum address (0x...40 hex chars).
- lat and lng are numbers (coordinates).
- estimatedCostOfPowerPerKWh and estimatedKWhGeneratedPerYear are numbers.
- installerCompanyName is a string.

---

✨ Usage Example

$3

`ts
import { createGlowEventListener, getZoneId } from "@glowlabs-org/events-sdk";

const listener = createGlowEventListener({
username: "listener",
password: "your-password-here",
zoneId: getZoneId("CleanGridProject"),
queueName: "my.precreated.queue",
host: "my.rabbitmq.host:5672", // Optional: override the default host
});

listener.onEvent("audit.pushed", "v1", (event) => {
// event: GlowEvent
console.log(
"Received audit.pushed v1:",
event.payload.farmId,
event.zoneId,
event.zoneName
);
});

listener.onEvent("audit.slashed", "v1", (event) => {
// event: GlowEvent
console.log(
"Received audit.slashed v1:",
event.payload.farmId,
event.payload.slasher
);
});

listener.onEvent("audit.pfees.paid", "v1", (event) => {
// event: GlowEvent
console.log(
"Received audit.pfees.paid v1:",
event.payload.applicationId,
event.payload.payer,
event.payload.amount_6Decimals
);
});

listener.onEvent("audit.pfees.paid", "v2", (event) => {
// event: GlowEvent
console.log(
"Received audit.pfees.paid v2:",
event.payload.farmId,
event.payload.payer,
event.payload.amount_12Decimals
);
});

listener.onEvent("application.created", "v1", (event) => {
// event: GlowEvent
console.log(
"Received application.created v1:",
event.payload.gcaAddress,
event.payload.lat,
event.payload.lng,
event.payload.estimatedCostOfPowerPerKWh,
event.payload.estimatedKWhGeneratedPerYear,
event.payload.installerCompanyName
);
});

await listener.start();
// To stop listening:
// await listener.stop();
`

$3

`ts
import { createGlowEventEmitter, getZoneId } from "@glowlabs-org/events-sdk";

// You must construct the emitter with a specific zoneId (not 0)
const emitter = createGlowEventEmitter({
username: "admin",
password: "your-password-here",
zoneId: getZoneId("CleanGridProject"), // must be a specific zone
host: "my.rabbitmq.host:5672", // Optional: override the default host
environment: "staging", // Optional: defaults to "production"
});

await emitter.emit({
eventType: "audit.pushed",
schemaVersion: "v1",
payload: {
farmId: "afbc56b6-0b16-4119-b144-025728067ba6", // UUID string
protocolFeeUSDPrice_6Decimals: "...",
expectedProduction_12Decimals: "...",
txHash: "0x...",
},
});

await emitter.emit({
eventType: "audit.slashed",
schemaVersion: "v1",
payload: {
farmId: "0x...",
slasher: "0x...",
txHash: "0x...",
},
});

await emitter.emit({
eventType: "audit.pfees.paid",
schemaVersion: "v1",
payload: {
applicationId: "3ed964b1-4f02-475a-9789-fb74b3466c70", // UUID string
payer: "0x...",
amount_6Decimals: "1000000000000",
txHash: "0x...",
},
});

await emitter.emit({
eventType: "audit.pfees.paid",
schemaVersion: "v2",
payload: {
farmId: "0x...",
payer: "0x...",
amount_12Decimals: "1000000000000",
txHash: "0x...",
},
});

await emitter.emit({
eventType: "application.created",
schemaVersion: "v1",
payload: {
gcaAddress: "0x...",
lat: 45.5017,
lng: -73.5673,
estimatedCostOfPowerPerKWh: 0.12,
estimatedKWhGeneratedPerYear: 10000,
installerCompanyName: "SolarCo",
},
});

await emitter.disconnect();
`

> Note:
>
> - The emitter will automatically publish each event to both the global (zone 0) and the specific zone exchange.
> - You cannot construct an emitter for zoneId: 0, and you cannot specify zoneId per emit call.
> - schemaVersion is always a string (e.g., "v1", "v2", "v2-alpha").
> - You can override the RabbitMQ host using the host option. Default is turntable.proxy.rlwy.net:50784.

$3

You can listen to all zones at once by passing zoneId: 0 and zoneName: "All Zones" to the listener. Emitters must always use a specific zone.

#### Listen to All Zones

`ts
import { createGlowEventListener } from "@glowlabs-org/events-sdk";

const listener = createGlowEventListener({
username: "listener",
password: "your-password-here",
zoneId: 0, // special value for all zones
queueName: "my.precreated.queue",
});

listener.onEvent("audit.pushed", "v1", (event) => {
console.log(
"Received audit.pushed v1 from any zone:",
event.payload.farmId,
event.zoneId,
event.zoneName
);
});

// ... other event handlers ...

await listener.start();
// To stop listening:
// await listener.stop();
`

---

🧪 Validation & Error Handling

- All events are validated at runtime using Zod schemas.
- If you emit or process an event with a zoneName that does not match the zoneId, an error is thrown. zoneId: 0 and zoneName: "All Zones" are a valid pairing.
- If you emit or process an event with a schemaVersion for which no schema exists (e.g., audit.pushed v2), an error is thrown.
- If the payload does not match the schema, an error is thrown.

---

🔐 Permissions & Credentials

- Listener credentials: Can only subscribe to events. Cannot emit events or create new queues.
- Admin credentials: Can subscribe, emit events, and create/bind new queues and exchanges.

If you try to emit with listener credentials, the SDK will throw an error.

---

🛠️ Admin & Queue Management

The SDK exposes helpers for programmatically creating, binding, and deleting exchanges and queues (admin credentials required). Use these for pre-creating queues for listeners, bootstrapping environments, or advanced queue management.

$3

Creates a topic exchange (default: exchangeType = "topic").

$3

Binds a queue to a topic exchange. You can specify a routingKey for fine-grained event filtering:

- routingKey = "#" (default): all events
- routingKey = "audit.pushed.v1": only audit.pushed v1 events
- routingKey = "audit.pushed.*": all versions of audit.pushed

#### Example

`ts
import {
createExchange,
bindQueueToExchange,
deleteExchange,
deleteQueue,
} from "@glowlabs-org/events-sdk";

await createExchange({
username: "admin",
password: "your-password-here",
exchange: "glow.zone-1.events",
});

await bindQueueToExchange({
username: "admin",
password: "your-password-here",
exchange: "glow.zone-1.events",
queue: "glow-listener-queue",
routingKey: "audit.pushed.v1", // only audit.pushed v1 events
});
`

---

🔒 Strict Read-Only Listeners

If your listener credentials only have read permission (no configure), you must consume from a pre-created queue. This is the most secure pattern for production.

$3

`ts
import { bindQueueToExchange } from "@glowlabs-org/events-sdk";

await bindQueueToExchange({
username: "admin",
password: "your-admin-password",
exchange: "glow.zone-1.events",
queue: "my.precreated.queue",
routingKey: "audit.pushed.v1", // only audit.pushed v1 events
});
`

$3

`ts
import { createGlowEventListener } from "@glowlabs-org/events-sdk";

const listener = createGlowEventListener({
username: "listener",
password: "your-listener-password",
zoneId: 1,
queueName: "my.precreated.queue",
});
`

- The listener will only consume from the pre-created queue and will not attempt to create or bind anything.
- This pattern is required for production environments with strict access control.

---

🧩 Advanced: Multiple Listeners/Emitters

You can create multiple listeners or emitters in the same process, each with its own configuration (e.g., for different credentials, exchanges, or RabbitMQ URLs). This is useful for multi-tenant, multi-topic, or advanced scenarios. Every listener receives every event for the bound routing key(s).

---

🧪 Extending Event Types

To add new event types or versions:

1. Create a new schema in src/schemas/.
2. Add the event type and version to eventTypeRegistry in src/event-registry.ts.
3. Update the base event type in src/base-event.ts if needed.

---

🏗️ Build & Publish to npm

To build and publish the SDK to npm:

`bash
make build
make publish
make clean
`

- The first time, run npm login to authenticate with npm.
- For scoped packages (like @glowlabs-org/events-sdk), the Makefile uses --access public` for publishing.

---

License

MIT