@tixyel/streamelements 2.0.0 → 3.0.1

package/README.md

@@ -0,0 +1,40 @@
+# @tixyel/streamelements
+
+TypeScript/JavaScript helper library for building custom widgets for [StreamElements](https://streamelements.com/), focused on productivity, type safety, and local development. Designed for browser usage via CDN, with TypeScript types for IDE autocompletion.
+
+## Features
+
+- **Typed event helpers** for Twitch, YouTube, and Kick (in development)
+- **Utility functions** for common widget tasks
+- **TypeScript types** for all major StreamElements events
+- **Local development support**: Test your widget locally without uploading to StreamElements
+- **Easy integration**: Use directly in the browser via CDN
+
+## Usage
+
+Add the following to your HTML:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@tixyel/streamelements"></script>
+<script>
+  const { Client, Simulation, logger } = window.Tixyel;
+
+  new Client({ id: 'my-widget' }).on('load', (event) => {
+    logger.received('Widget loaded!', event);
+  });
+</script>
+```
+
+> **Note:** This package is designed for browser usage via CDN only.
+> TypeScript is used only to provide type definitions and autocompletion in your IDE when working with `window.Tixyel`.
+
+## API Overview
+
+- **Client**: Manages events and integration with StreamElements.
+- **Simulation**: Simulates events for local testing.
+- **Logger**: Utility for formatted logs.
+- **Button/Command**: Helpers for custom actions.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -545,6 +545,12 @@ declare enum Alejo$Pronouns {
     itits = "It/Its"
 }
 type Alejo$Pronouns$name = 'hehim' | 'sheher' | 'theythem' | 'shethem' | 'hethem' | 'heshe' | 'xexem' | 'faefaer' | 'vever' | 'aeaer' | 'ziehir' | 'perper' | 'eem' | 'itits';
+type Alejo$Pronouns$display = 'He/Him' | 'She/Her' | 'They/Them' | 'She/They' | 'He/They' | 'He/She' | 'Xe/Xem' | 'Fae/Faer' | 'Ve/Ver' | 'Ae/Aer' | 'Zie/Hir' | 'Per/Per' | 'E/Em' | 'It/Its';
+type Alejo$Pronouns$User = {
+    id: string;
+    login: string;
+    pronouns: Alejo$Pronouns$name;
+};
 
 /**
  * EventProvider class for managing event listeners and emitters.
@@ -610,6 +616,7 @@ type MapNumberValuesToString<T> = {
 type UseStorageEvents<T> = {
     load: [T | null];
     save: [T];
+    update: [T];
 };
 type UseStorageOptions<T> = {
     id?: string;
@@ -628,8 +635,25 @@ declare class useStorage<T extends object = Record<string, any>> extends EventPr
      * @param data Data to save (defaults to current)
      */
     save(data?: T): void;
+    /**
+     * Updates the storage data and emits an update event if the data has changed.
+     * @param data Data to update (defaults to current)
+     */
+    update(data?: T): void;
+    /**
+     * Adds a value to the storage at the specified path.
+     * @param path Path to add the value to
+     * @param value Value to add
+     */
     add<P extends string>(path: P, value: PathValue<T, P>): void;
-    setByPath<P extends string>(obj: T, path: P, value: PathValue<T, P>): void;
+    /**
+     * Sets a value in the storage at the specified path.
+     * @param obj The object to set the value in
+     * @param path The path to set the value at
+     * @param value The value to set
+     * @returns The updated object
+     */
+    static setByPath<P extends string, T extends object>(obj: T, path: P, value: PathValue<T, P>): void;
     on<K extends keyof UseStorageEvents<T>>(eventName: K, callback: (...args: UseStorageEvents<T>[K]) => void): this;
 }
 
@@ -637,7 +661,9 @@ type StreamElements$AlertService = {
     listener: 'alertService:toggleSound';
     event: toggleSound;
 };
-type toggleSound = {};
+type toggleSound = {
+    muted: boolean;
+};
 
 type StreamElements$BotCounter = {
     listener: 'bot:counter';
@@ -776,7 +802,7 @@ type StreamElements$KVStore = {
 type KVStore = {
     data: {
         key: `customWidget.${string}`;
-        value: string | number | boolean;
+        value: string | number | boolean | Record<string, any>;
     };
 };
 
@@ -830,19 +856,6 @@ type Follower = {
     originalEventName: 'follower-latest';
 };
 
-type Twitch$DeleteMessage = {
-    listener: 'delete-message';
-    event: {
-        msgId: string;
-    };
-};
-type Twitch$DeleteMessages = {
-    listener: 'delete-messages';
-    event: {
-        userId: string;
-    };
-};
-
 type Twitch$IRC = {
     /**
      * Contains metadata related to the chat badges in the badges tag.
@@ -992,6 +1005,19 @@ type Twitch$IRC = {
     'vip': undefined | '';
 };
 
+type Twitch$DeleteMessage = {
+    listener: 'delete-message';
+    event: {
+        msgId: string;
+    };
+};
+type Twitch$DeleteMessages = {
+    listener: 'delete-messages';
+    event: {
+        userId: string;
+    };
+};
+
 type Twitch$Message = {
     listener: 'message';
     event: Message;
@@ -1318,10 +1344,10 @@ declare class Button {
 }
 
 type ClientEvents = {
-    load: [event: onWidgetLoad];
-    action: [action: any, type: 'created' | 'updated' | 'executed'];
-    session: [session: Session$1];
-    event: [event: ClientEvents$1];
+    load: [this: Client, event: onWidgetLoad];
+    action: [this: Client, action: Button | Command, type: 'created' | 'executed'];
+    session: [this: Client, session: Session$1];
+    event: [this: Client, event: ClientEvents$1];
 };
 type ClientOptions = {
     id?: string;
@@ -1630,21 +1656,94 @@ declare class Logger implements LoggerMethods {
     constructor();
 }
 
+type Emote = TwitchEmote | BttvEmote | SeventvEmote;
+declare function findEmotesInText(text: string, emotes?: Emote[]): Emote[];
+declare function replaceEmotesWithHTML(text: string, emotes: Emote[]): string;
+
+type QueueEvents<T> = {
+    load: [];
+    cancel: [];
+    update: [queue: QueueItem<T>[], priorityQueue: QueueItem<T>[], history: QueueItem<T>[], timeouts: Array<ReturnType<typeof setTimeout>>];
+    process: [item: QueueItem<T>, queue: useQueue<T>];
+};
+type QueueProps = {
+    isoDate: string;
+    isLoop: boolean;
+    isPriority: boolean;
+    isImmediate: boolean;
+};
+type QueueItem<T> = {
+    value: T;
+} & QueueProps;
+type QueueProcessor<T> = (item: T, queue: useQueue<T>) => Promise<any>;
+interface QueueOptions<T> {
+    duration: number | boolean | undefined;
+    processor: QueueProcessor<T>;
+}
+declare class useQueue<T> extends EventProvider<QueueEvents<T>> {
+    queue: QueueItem<T>[];
+    priorityQueue: QueueItem<T>[];
+    history: QueueItem<T>[];
+    timeouts: Array<ReturnType<typeof setTimeout>>;
+    running: boolean;
+    duration: number | boolean | undefined;
+    loaded: boolean;
+    processor: QueueProcessor<T>;
+    constructor(options: QueueOptions<T>);
+    enqueue(value: T, options?: Partial<QueueProps>): this;
+    private run;
+    private next;
+    resume(): this;
+    update(save: Partial<useQueue<T>>): this;
+    cancel(): void;
+    hasItems(): boolean;
+}
+
 declare const Tixyel: {
+    readonly Client: typeof Client;
+    readonly Simulation: typeof Simulation;
+    readonly logger: Logger;
+    readonly utils: {
+        readonly findEmotesInText: typeof findEmotesInText;
+        readonly replaceEmotesWithHTML: typeof replaceEmotesWithHTML;
+    };
+    readonly modules: {
+        readonly Button: typeof Button;
+        readonly Command: typeof Command;
+        readonly EventProvider: typeof EventProvider;
+        readonly useStorage: typeof useStorage;
+        readonly useQueue: typeof useQueue;
+    };
+};
+type _Tixyel_ = {
     Client: typeof Client;
     Simulation: typeof Simulation;
     logger: Logger;
+    utils: {
+        findEmotesInText: typeof findEmotesInText;
+        replaceEmotesWithHTML: typeof replaceEmotesWithHTML;
+    };
+    modules: {
+        Button: typeof Button;
+        Command: typeof Command;
+        EventProvider: typeof EventProvider;
+        useStorage: typeof useStorage;
+        useQueue: typeof useQueue;
+    };
 };
 declare global {
     interface Window {
-        Tixyel: typeof Tixyel;
-        client?: Client;
+        Tixyel: _Tixyel_;
+        client: Client;
     }
     interface WindowEventMap {
-        'onWidgetLoad': onWidgetLoadEvent;
-        'onSessionUpdate': onSessionUpdateEvent;
-        'onEventReceived': onEventReceivedEvent;
+        onWidgetLoad: onWidgetLoadEvent;
+        onSessionUpdate: onSessionUpdateEvent;
+        onEventReceived: onEventReceivedEvent;
     }
+    var Tixyel: _Tixyel_;
+    var client: Client;
 }
 
-export { Tixyel };
+export { Alejo$Pronouns, Tixyel };
+export type { Alejo$Pronouns$User, Alejo$Pronouns$display, Alejo$Pronouns$name, BttvEmote, ClientEvents$1 as ClientEvents, Facebook, Kick, Provider, SeventvEmote, StreamElements, Twitch, Twitch$Cheer, Twitch$DeleteMessage, Twitch$DeleteMessages, Twitch$Follower, Twitch$IRC, Twitch$Message, Twitch$Raid, Twitch$Subscriber, TwitchBadge, TwitchBadgesKeys, TwitchEmote, Youtube };