@allior/wmake-streamelements-events 0.0.1

package/src/root/aggregate.ts

@@ -0,0 +1,258 @@
+/**
+ * Event normalizer — aggregate mode: buffer events by activityGroup,
+ * merge into one normalized event per action (timeout 2.5s).
+ */
+
+import { classifyEvent, getCacheKey } from "./classifier.js";
+import type {
+  IncomingDetail,
+  NormalizerOptions,
+  CacheSubsByType,
+  ClassifiedEvent,
+} from "./types/on-event-received.js";
+
+const AGGREGATE_TIMEOUT_MS = 2500;
+
+interface BufferEntry {
+  type: string;
+  subscribers: Array<{
+    recipient?: string;
+    username?: string;
+    name?: string;
+    sender?: string;
+  }>;
+  tier: number;
+  tierText: string;
+  totalAmount: number;
+  purchase?: ClassifiedEvent;
+  sender?: string;
+}
+
+const bufferByGroup: Record<string, BufferEntry> = {};
+const bufferTimers: Record<string, ReturnType<typeof setTimeout>> = {};
+
+function getCacheForType(
+  cacheSubs: CacheSubsByType | undefined,
+  type: string,
+): {
+  _has: (k: string) => boolean;
+  _set: (k: string, v: boolean) => void;
+} | null {
+  if (!cacheSubs) return null;
+  if (
+    typeof cacheSubs._has === "function" &&
+    typeof cacheSubs._set === "function"
+  ) {
+    return cacheSubs as unknown as {
+      _has: (k: string) => boolean;
+      _set: (k: string, v: boolean) => void;
+    };
+  }
+  const c = cacheSubs[type];
+  return c && typeof (c as { _has?: unknown })._has === "function"
+    ? (c as {
+        _has: (k: string) => boolean;
+        _set: (k: string, v: boolean) => void;
+      })
+    : null;
+}
+
+function emitAggregated(
+  groupKey: string,
+  merged: Record<string, unknown>,
+  cacheSubs: CacheSubsByType | undefined,
+  onNormalized: (event: ClassifiedEvent | null) => void,
+): void {
+  const cache = getCacheForType(cacheSubs, merged.type as string);
+  if (cache && cache._has(groupKey)) return;
+  if (cache) cache._set(groupKey, true);
+  onNormalized(merged as ClassifiedEvent);
+}
+
+function flushBuffer(
+  groupKey: string,
+  cacheSubs: CacheSubsByType | undefined,
+  onNormalized: (event: ClassifiedEvent | null) => void,
+  broadcaster: string,
+): void {
+  const buf = bufferByGroup[groupKey];
+  if (!buf) return;
+  delete bufferByGroup[groupKey];
+  if (bufferTimers[groupKey]) {
+    clearTimeout(bufferTimers[groupKey]);
+    delete bufferTimers[groupKey];
+  }
+  const purchase = buf.purchase as Record<string, unknown> | undefined;
+  const subscribers = buf.subscribers ?? [];
+  const type = buf.type;
+  const tier = buf.tier;
+  const tierText = buf.tierText;
+  const totalAmount = buf.totalAmount ?? subscribers.length;
+  const recipients = subscribers
+    .map((s) => s.recipient ?? s.username ?? s.name)
+    .filter(Boolean) as string[];
+  const firstSub = subscribers[0];
+  const senderFromSub = firstSub?.sender;
+  const sender = purchase?.sender ?? buf.sender ?? senderFromSub;
+  if (type === "community-gift" && broadcaster && sender === broadcaster) {
+    return;
+  }
+  if (type === "community-gift-anonymous") {
+    emitAggregated(
+      groupKey,
+      {
+        type: "community-gift-anonymous",
+        tier,
+        tierText,
+        totalAmount,
+        recipients,
+        anonymousDisplayName: purchase?.anonymousDisplayName,
+      },
+      cacheSubs,
+      onNormalized,
+    );
+  } else {
+    emitAggregated(
+      groupKey,
+      {
+        type: "community-gift",
+        sender,
+        tier,
+        tierText,
+        totalAmount,
+        recipients,
+      },
+      cacheSubs,
+      onNormalized,
+    );
+  }
+}
+
+/**
+ * Normalizes an incoming subscription event (StreamElements/Twitch).
+ * Buffers community-gift recipients by activityGroup, then emits one normalized event per group.
+ * For self-sub, solo-sub, sub-renewal emits immediately (with optional cache dedup).
+ */
+export function normalizeIncomingEvent(
+  detail: IncomingDetail,
+  options: NormalizerOptions | undefined,
+  onNormalized: (event: ClassifiedEvent | null) => void,
+): void {
+  const cacheSubs = options?.cacheSubs;
+  const broadcaster = options?.broadcasterLogin ?? "";
+
+  const classified = classifyEvent(detail);
+  if (!classified) {
+    onNormalized(null);
+    return;
+  }
+
+  const cache = getCacheForType(cacheSubs, classified.type);
+  const cacheKey = getCacheKey(detail);
+  const event = detail.event ?? {};
+  const data = (event.data ?? event) as Record<string, unknown>;
+
+  if ((classified as Record<string, unknown>)._role === "recipient") {
+    const ag =
+      ((classified as Record<string, unknown>).activityGroup as string) ??
+      cacheKey;
+    if (!bufferByGroup[ag]) {
+      bufferByGroup[ag] = {
+        type: classified.type,
+        subscribers: [],
+        tier: classified.tier,
+        tierText: classified.tierText,
+        totalAmount: 0,
+      };
+    }
+    if (bufferTimers[ag]) clearTimeout(bufferTimers[ag]);
+    bufferTimers[ag] = setTimeout(() => {
+      flushBuffer(ag, cacheSubs, onNormalized, broadcaster);
+    }, AGGREGATE_TIMEOUT_MS);
+    bufferByGroup[ag].subscribers.push({
+      recipient: (classified as Record<string, unknown>).recipient as string,
+      username: data.username as string,
+      name: data.displayName as string,
+      sender: data.sender as string,
+    });
+    if (bufferByGroup[ag].totalAmount === 0) bufferByGroup[ag].totalAmount = 1;
+    return;
+  }
+
+  if (
+    classified.type === "community-gift-anonymous" ||
+    classified.type === "community-gift"
+  ) {
+    const isPurchase =
+      detail.listener === "event" && event.type === "communityGiftPurchase";
+    if (isPurchase) {
+      const ag = (event.activityGroup ??
+        (data && data.activityGroup) ??
+        cacheKey) as string;
+      if (!bufferByGroup[ag]) {
+        bufferByGroup[ag] = {
+          type: classified.type,
+          purchase: classified,
+          subscribers: [],
+          tier: classified.tier,
+          tierText: classified.tierText,
+          totalAmount:
+            Number((classified as Record<string, unknown>).totalAmount) || 0,
+          sender: (classified as Record<string, unknown>).sender as string,
+        };
+        bufferTimers[ag] = setTimeout(() => {
+          flushBuffer(ag, cacheSubs, onNormalized, broadcaster);
+        }, AGGREGATE_TIMEOUT_MS);
+      } else {
+        bufferByGroup[ag].purchase = classified;
+        bufferByGroup[ag].tier = classified.tier;
+        bufferByGroup[ag].tierText = classified.tierText;
+        bufferByGroup[ag].totalAmount =
+          ((classified as Record<string, unknown>).totalAmount as number) ??
+          bufferByGroup[ag].totalAmount;
+        bufferByGroup[ag].sender = (classified as Record<string, unknown>)
+          .sender as string;
+        if (bufferTimers[ag]) clearTimeout(bufferTimers[ag]);
+        bufferTimers[ag] = setTimeout(() => {
+          flushBuffer(ag, cacheSubs, onNormalized, broadcaster);
+        }, AGGREGATE_TIMEOUT_MS);
+      }
+      return;
+    }
+    if (detail.listener === "subscriber-latest") {
+      const c = classified as Record<string, unknown>;
+      if (
+        classified.type === "community-gift" &&
+        broadcaster &&
+        c.sender === broadcaster
+      ) {
+        onNormalized(null);
+        return;
+      }
+      return;
+    }
+    return;
+  }
+
+  if (
+    classified.type === "self-sub" ||
+    classified.type === "solo-sub-to-someone" ||
+    classified.type === "sub-renewal"
+  ) {
+    if (cache?._has(cacheKey)) {
+      onNormalized(null);
+      return;
+    }
+    if (cache) cache._set(cacheKey, true);
+    const c = classified as Record<string, unknown>;
+    if (
+      classified.type === "solo-sub-to-someone" &&
+      broadcaster &&
+      c.sender === broadcaster
+    ) {
+      onNormalized(null);
+      return;
+    }
+    onNormalized(classified);
+  }
+}

package/src/root/classifier.ts

@@ -0,0 +1,208 @@
+/**
+ * Shared classification and tier parsing for Twitch/StreamElements subscription events.
+ * Used by aggregate normalizer.
+ */
+
+import type {
+  IncomingDetail,
+  TierInfo,
+  ClassifiedEvent,
+} from "./types/on-event-received.js";
+
+export function parseTier(raw: string | number | null | undefined): TierInfo {
+  if (raw == null) return { tier: 0, tierText: "" };
+  const tierText = typeof raw === "string" ? raw : String(raw);
+  const num = parseInt(tierText, 10);
+  if (isNaN(num)) return { tier: 0, tierText };
+  const tier = num >= 3000 ? 3 : num >= 2000 ? 2 : num >= 1000 ? 1 : 0;
+  return { tier, tierText };
+}
+
+export function getCacheKey(detail: IncomingDetail): string {
+  const listener = detail.listener;
+  const event = detail.event ?? {};
+  const ag = event.activityGroup;
+  const aid = event.activityId ?? event._id;
+  if (ag) return String(ag);
+  if (aid) return String(aid);
+  if (listener === "subscriber-latest" && event.bulkGifted) {
+    return (
+      "sl-bulk-" +
+      (event.sender ?? "") +
+      "-" +
+      (event.amount ?? "") +
+      "-" +
+      (event.tier ?? "") +
+      "-" +
+      (event._id ?? "")
+    );
+  }
+  return "sl-" + (event._id ?? event.activityId ?? "");
+}
+
+export function classifyEvent(detail: IncomingDetail): ClassifiedEvent | null {
+  const listener = detail.listener;
+  const event = detail.event ?? {};
+  const data = (event.data ?? event) as Record<string, unknown>;
+  const tierInfo = parseTier(
+    (data.tier ?? event.tier) as string | number | undefined,
+  );
+
+  if (listener === "event") {
+    if (event.type === "communityGiftPurchase") {
+      const isAnon =
+        (data.username &&
+          String(data.username).toLowerCase() === "anonymous") ||
+        data.sender === "Anonymous";
+      return {
+        type: isAnon ? "community-gift-anonymous" : "community-gift",
+        tier: tierInfo.tier,
+        tierText: tierInfo.tierText,
+        totalAmount: parseInt(String(data.amount), 10) || 1,
+        recipients: [],
+        sender: isAnon
+          ? undefined
+          : ((data.sender ?? data.displayName ?? data.username) as string),
+        anonymousDisplayName: isAnon
+          ? ((data.displayName as string) ?? "Anonymous")
+          : undefined,
+      };
+    }
+    if (event.type === "subscriber") {
+      const gifted = data.gifted === true;
+      const sender = data.sender as string | undefined;
+      const amount = parseInt(String(data.amount), 10) || 1;
+      const username = (data.username ?? data.displayName) as
+        | string
+        | undefined;
+      const activityGroup = event.activityGroup as string | undefined;
+
+      if (sender === "Anonymous" && activityGroup) {
+        return {
+          type: "community-gift-anonymous",
+          _role: "recipient",
+          activityGroup,
+          recipient: (username ?? data.displayName) as string,
+          tier: tierInfo.tier,
+          tierText: tierInfo.tierText,
+        };
+      }
+      if (gifted && sender && sender !== "Anonymous") {
+        const isCommunity =
+          data.communityGifted === true ||
+          (activityGroup != null && activityGroup !== "");
+        if (!isCommunity) {
+          const firstGift =
+            String(data.message ?? "").indexOf("first Gift Sub") !== -1;
+          return {
+            type: "solo-sub-to-someone",
+            sender,
+            recipient: (username ?? data.displayName) as string,
+            tier: tierInfo.tier,
+            tierText: tierInfo.tierText,
+            firstGiftInChannel: firstGift,
+          };
+        }
+        return {
+          type: "community-gift",
+          _role: "recipient",
+          activityGroup: activityGroup!,
+          recipient: (username ?? data.displayName) as string,
+          tier: tierInfo.tier,
+          tierText: tierInfo.tierText,
+        };
+      }
+      if (!gifted && amount > 1) {
+        return {
+          type: "sub-renewal",
+          name: (username ?? data.displayName) as string,
+          months: amount,
+          tier: tierInfo.tier,
+          tierText: tierInfo.tierText,
+        };
+      }
+      if (!gifted && amount === 1) {
+        return {
+          type: "self-sub",
+          name: (username ?? data.displayName) as string,
+          tier: tierInfo.tier,
+          tierText: tierInfo.tierText,
+        };
+      }
+      if (activityGroup) {
+        return {
+          type: "community-gift",
+          _role: "recipient",
+          activityGroup,
+          recipient: (username ?? data.displayName) as string,
+          tier: tierInfo.tier,
+          tierText: tierInfo.tierText,
+        };
+      }
+      return null;
+    }
+    return null;
+  }
+
+  if (listener === "subscriber-latest") {
+    const bulkGifted = event.bulkGifted === true;
+    const sender = event.sender as string | undefined;
+    const name = event.name as string | undefined;
+    const amount = parseInt(String(event.amount), 10) || 1;
+    const gifted = event.gifted === true;
+    const isCommunityGift =
+      event.isCommunityGift === true || event.communityGifted === true;
+
+    if (bulkGifted && sender === "Anonymous") {
+      return {
+        type: "community-gift-anonymous",
+        tier: tierInfo.tier,
+        tierText: tierInfo.tierText,
+        totalAmount: amount,
+        recipients: [],
+      };
+    }
+    if (bulkGifted && sender) {
+      return {
+        type: "community-gift",
+        sender,
+        tier: tierInfo.tier,
+        tierText: tierInfo.tierText,
+        totalAmount: amount,
+        recipients: [],
+      };
+    }
+    if (gifted && !isCommunityGift && sender) {
+      const firstGift =
+        String(event.message ?? "").indexOf("first Gift Sub") !== -1;
+      return {
+        type: "solo-sub-to-someone",
+        sender,
+        recipient: name ?? "",
+        tier: tierInfo.tier,
+        tierText: tierInfo.tierText,
+        firstGiftInChannel: firstGift,
+      };
+    }
+    if (!gifted && amount > 1) {
+      return {
+        type: "sub-renewal",
+        name: name ?? "",
+        months: amount,
+        tier: tierInfo.tier,
+        tierText: tierInfo.tierText,
+      };
+    }
+    if (!gifted && amount === 1 && (sender == null || name === sender)) {
+      return {
+        type: "self-sub",
+        name: name ?? "",
+        tier: tierInfo.tier,
+        tierText: tierInfo.tierText,
+      };
+    }
+    return null;
+  }
+
+  return null;
+}

package/src/root/commands.ts

@@ -0,0 +1,33 @@
+/**
+ * Команды, вызывающие onEventReceived с тестовыми сообщением или алертом.
+ * Работают только в браузере (требуется window).
+ */
+import { testMessages, testAlerts } from "./sources";
+
+const EVENT_NAME = "onEventReceived";
+
+/**
+ * Отправляет тестовое сообщение по ключу: диспатчит CustomEvent onEventReceived.
+ */
+export function testMessage(key: string): void {
+  if (typeof window === "undefined") {
+    return;
+  }
+  const msg = testMessages[key as keyof typeof testMessages];
+  if (msg) {
+    window.dispatchEvent(new CustomEvent(EVENT_NAME, { detail: msg }));
+  }
+}
+
+/**
+ * Отправляет тестовый алерт по ключу: диспатчит CustomEvent onEventReceived.
+ */
+export function testAlert(key: string): void {
+  if (typeof window === "undefined") {
+    return;
+  }
+  const alert = testAlerts[key as keyof typeof testAlerts];
+  if (alert) {
+    window.dispatchEvent(new CustomEvent(EVENT_NAME, { detail: alert }));
+  }
+}

package/src/root/data/event-detail.ts

@@ -0,0 +1,14 @@
+export interface EventDetail<T = string, R = unknown> {
+  listener: T;
+  event: R;
+}
+
+export type FollowerLatestDetail = EventDetail<"follower-latest">;
+
+export type WidgetButtonDetail = EventDetail<
+  "event:test",
+  {
+    listener: "widget-button";
+    field: string;
+  }
+>;

package/src/root/data/field-value.ts

@@ -0,0 +1,2 @@
+/** Минимальный тип для fieldData в WidgetLoadDetail (без зависимости от streamelements). */
+export type FieldValue = string | number | boolean | undefined | null;

package/src/root/data/index.ts

@@ -0,0 +1,2 @@
+export * from "./event-detail";
+export * from "./widget-load";

package/src/root/data/widget-load.ts

@@ -0,0 +1,5 @@
+import type { FieldValue } from "./field-value.js";
+
+export interface WidgetLoadDetail {
+  fieldData: Record<string, FieldValue>;
+}

package/src/root/index.ts

@@ -0,0 +1,9 @@
+export * from "./classifier.js";
+export * from "./aggregate.js";
+export * from "./types";
+import "./window-event-map";
+export * from "./data";
+export * from "./sources/index";
+export * from "./commands";
+export * from "./keys";
+export * from "./message";

package/src/root/keys.ts

@@ -0,0 +1,14 @@
+/**
+ * Преобразование fieldId виджета в ключ тестовых данных.
+ */
+export function getTestMessageKey(fieldId: string): string | null {
+  if (!fieldId.startsWith("testMessage")) return null;
+  const name = fieldId.replace("testMessage", "");
+  return name.charAt(0).toLowerCase() + name.slice(1);
+}
+
+export function getTestAlertKey(fieldId: string): string | null {
+  if (!fieldId.startsWith("testAlert")) return null;
+  const name = fieldId.replace("testAlert", "");
+  return name.charAt(0).toLowerCase() + name.slice(1);
+}

package/src/root/message/event.ts

@@ -0,0 +1,7 @@
+import type { Message } from "./message";
+
+/** Событие сообщения чата (формат onEventReceived, listener "message"). */
+export interface MessageEvent {
+  listener: "message";
+  event: Message.Event;
+}

package/src/root/message/index.ts

@@ -0,0 +1,4 @@
+export * from "./event"
+export * from "./message"
+export * from "./roles"
+export * from "./tags"

package/src/root/message/message.ts

@@ -0,0 +1,40 @@
+import type { TwitchMessageTags } from "./tags";
+
+export namespace Message {
+  export interface Event {
+    service: "twitch";
+    data: Data;
+    renderedText: string;
+  }
+
+  export interface Data {
+    tags: TwitchMessageTags;
+    nick: string;
+    userId: string;
+    displayName: string;
+    displayColor?: string;
+    badges: Array<Badge>;
+    channel: string;
+    text: string;
+    isAction: boolean;
+    emotes: Array<Emote>;
+    msgId: string;
+    time?: number;
+  }
+
+  export interface Badge {
+    type: string;
+    version?: string;
+    url?: string;
+    description?: string;
+  }
+
+  export interface Emote {
+    type: string;
+    name: string;
+    id: string;
+    urls: Record<string, string>;
+    start?: number;
+    end?: number;
+  }
+}

package/src/root/message/roles.ts

@@ -0,0 +1,43 @@
+import {
+  isArtist,
+  isBroadcaster,
+  isModerator,
+  isSubscriber,
+  isTurbo,
+  isVip,
+  type TwitchMessageTags,
+} from "./tags";
+
+export type UserRole =
+  | "broadcaster"
+  | "moderator"
+  | "vip"
+  | "artist"
+  | "subscriber"
+  | "turbo"
+  | "default";
+
+export function determineUserRoles(
+  tags: TwitchMessageTags | Record<string, string>,
+): UserRole[] {
+  const roles: UserRole[] = ["default"];
+  if (isBroadcaster(tags)) {
+    roles.push("broadcaster");
+  }
+  if (isModerator(tags)) {
+    roles.push("moderator");
+  }
+  if (isVip(tags)) {
+    roles.push("vip");
+  }
+  if (isArtist(tags)) {
+    roles.push("artist");
+  }
+  if (isSubscriber(tags)) {
+    roles.push("subscriber");
+  }
+  if (isTurbo(tags)) {
+    roles.push("turbo");
+  }
+  return roles;
+}