@allior/wmake-streamelements-events

Twitch/StreamElements subscription event normalizer for widgets (alerts).

• shared — classification and tiers: parseTier, getCacheKey, classifyEvent.
• aggregator — buffer by activityGroup, one normalized event per group (2.5 s timeout): aggregateIncomingEvent.
• react — type-safe hooks for easy event handling.

Installation

In the wmake repo the package is already in workspaces. From the root:

npm i @allior/wmake-streamelements-events

Core Capabilities

1. Classification (classifyEvent)

Converts raw StreamElements CustomEvent data into clean, typed domain objects.

Supported Events:

• Followers: New channel follows.
• Cheers: Bit donations with amount and sender.
• Raids: Incoming raids with viewer count.
• Subscriptions:
  • self-sub: Personal subscription.
  • sub-renewal: Multi-month renewal.
  • solo-sub-to-someone: Single gift sub.
  • community-gift: Group gift subscriptions.
• Moderation:
  • delete-message: Single message removal (returns messageId).
  • delete-messages: Chat clear or user timeout (returns userName).
• Widgets: widget-button clicks from Overlay Editor.

2. Intelligent Aggregation

Buffers mass gift events to avoid alert spam. It groups multiple subscriber events into a single AggregatedCommunityGift action.

import { aggregateIncomingEvent } from "@allior/wmake-streamelements-events";

aggregateIncomingEvent(
  detail,
  { broadcasterLogin: "mychannel" },
  (normalized) => {
    // normalized contains .recipients list of everyone who got a sub
    if (normalized) console.log(normalized);
  },
);

React Hooks

Aggregated Community Gifts

The most efficient way to handle mass gifts in React.

import { useOnAggregatedCommunityGift } from "@allior/wmake-streamelements-events/react";

useOnAggregatedCommunityGift((event) => {
  console.log(`${event.sender} gifted ${event.totalAmount} subs to ${event.recipients.join(", ")}`);
}, { broadcasterLogin: "mychannel" });

Type-Safe Event Hooks

All hooks support two modes: Raw (default) and Classified.

import { 
  useOnFollowerReceived, 
  useOnDeleteMessage,
  useOnWidgetButtonReceived 
} from "@allior/wmake-streamelements-events/react";

// Mode A: Raw StreamElements Event
useOnFollowerReceived((ev) => {
  console.log("Raw event name:", ev.detail.event.name);
});

// Mode B: Classified Object (Type-safe)
useOnDeleteMessage((data) => {
  // data is ClassifiedDeleteMessage { messageId: string }
  console.log("User message deleted:", data.messageId);
}, { classified: true });

// Listen for SE Overlay Editor buttons
useOnWidgetButtonReceived((data) => {
  if (data.field === "myCustomButton") {
    console.log("Button clicked!");
  }
}, { classified: true });

API Reference

• classifyEvent(detail) — returns ClassifiedEvent | null.
• getCacheKey(detail) — unique key for deduplication.
• parseTier(raw) — transforms SE tier strings into { tier: 1|2|3, tierText }.
• aggregateIncomingEvent(detail, options, callback) — entry point for community-gift aggregation.

Advanced Caching

You can provide a CacheLike object to aggregator to persist handled groups across reloads.

npm i @allior/cache

useOnAggregatedCommunityGift(handler, { cacheSubs: new AlliorCache<string, boolean>() });