@pixl-app/sdk 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.1
+
+Das Script nimmt die eigene Adresse nur noch als Server, wenn es von einer pixl-Instanz kommt (`/sdk/pixl.js`). Von jsDelivr, unpkg oder einem lokalen Dev-Server geladen, verbindet es sich mit pixl.lennox.zip statt mit dem CDN. `baseUrl` geht weiter vor, an `https://pixl.lennox.zip/sdk/pixl.js` ändert sich nichts.
+
+## 0.1.0
+
+Erste Version im eigenen Repo: Live-Events per Stream, `feed()` mit Verlauf und Live-Events ohne Doppelte, Chat mit Emotes, Spotify, StreamElements, TTS, persistente States und Einstellungen für eigene Widgets.
+
+Neu gegenüber dem `/sdk/pixl.js`, das pixl.lennox.zip gerade ausliefert: `pixl.nowPlaying()` und `Pixl.progress()`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lennox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# pixl SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Holt die Events eines Kanals aus [pixl](https://pixl.lennox.zip) in eigene Widgets: Follows, Subs, Cheers, Raids, Kanalpunkte, Chat mit 7TV-, BTTV- und FFZ-Emotes, Spotify, StreamElements-Spenden und TTS. Läuft in StreamElements Custom Widgets, OBS-Browserquellen und jedem aktuellen Browser.
+
+Die ausführliche Doku steht unter [docs.pixl.lennox.zip/sdk](https://docs.pixl.lennox.zip/sdk).
+
+## Einbinden
+
+Per Script-Tag, ohne Installation:
+
+```html
+<script src="https://pixl.lennox.zip/sdk/pixl.js"></script>
+<script>
+	const pixl = new Pixl({ key: "pixl_DEIN_SCHLÜSSEL" });
+	pixl.on("twitch.follow", (data) => console.log(`${data.username} folgt jetzt`));
+</script>
+```
+
+Mit fester Version über jsDelivr. Unter `pixl.lennox.zip/sdk/pixl.js` kommt immer die Version, die pixl gerade ausliefert:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@pixl-app/sdk@0.1.1/dist/pixl.js"></script>
+```
+
+Oder als Paket mit Bundler und TypeScript:
+
+```bash
+bun add @pixl-app/sdk   # oder: npm i @pixl-app/sdk
+```
+
+```ts
+import { Pixl } from "@pixl-app/sdk";
+
+const pixl = new Pixl({ key: "pixl_DEIN_SCHLÜSSEL" });
+pixl.on("twitch.follow", (data) => console.log(`${data.username} folgt jetzt`));
+```
+
+Den API-Schlüssel legst du in pixl unter „API & SDK“ an. Welche Felder jedes Event mitbringt, steht in der Doku unter [Events](https://docs.pixl.lennox.zip/sdk/events).
+
+## Entwickeln
+
+```bash
+bun install
+bun run dev        # Dev-SDK unter http://localhost:4400/pixl.js, baut bei jeder Änderung neu
+bun run check      # Typen
+bun run lint       # Formatierung
+bun test           # Tests
+bun run build      # dist/pixl.js (Script), dazu dist/index.js und .d.ts
+```
+
+Ein Overlay mit dem Dev-SDK testen: `<script src="http://localhost:4400/pixl.js"></script>` einbinden. Es spricht dann mit pixl.lennox.zip, gegen einen lokalen pixl-Server zusätzlich `baseUrl` setzen. In einer OBS-Browserquelle oder einer lokalen HTML-Datei klappt das direkt, eine https-Seite wie StreamElements sperrt `http://localhost` unter Umständen.
+
+Die Typen der pixl-API liegen als Kopie aus dem pixl-Monorepo in `src/api-types/`, bis es dafür ein npm-Paket gibt. Geändert werden sie dort, nicht hier.
+
+Gegen eine lokale pixl-Instanz: `new Pixl({ key, baseUrl: "http://localhost:5173" })`.
+
+## Versionen und Releases
+
+Semver. Bricht eine Änderung bestehende Widgets, steigt die Hauptversion. Was sich geändert hat, steht im [CHANGELOG](./CHANGELOG.md).
+
+Jede Version landet auf [npm](https://www.npmjs.com/package/@pixl-app/sdk) und als [GitHub-Release](https://github.com/pixl-app/sdk/releases) mit `pixl.js` (Script für `<script src>`) und `pixl-app-sdk-<version>.tgz` (Paket mit ESM und `.d.ts`). So entsteht eine:
+
+1. Version in `package.json` anheben, in `CHANGELOG.md` einen Abschnitt `## 0.2.0` anlegen. Daraus werden die Release-Notizen.
+2. Tag `v0.2.0` pushen. Die CI prüft Version, Typen und Formatierung, baut, veröffentlicht auf npm (Trusted Publishing, ohne gespeicherten Token) und hängt beide Dateien an das Release.
+
+## Fehler melden
+
+Unter [Issues](https://github.com/pixl-app/sdk/issues), am besten mit SDK-Version, Browser oder OBS-Version und dem, was in der Konsole steht.
+
+## Lizenz
+
+MIT

package/dist/api-types/api-scopes.d.ts

@@ -0,0 +1,4 @@
+export declare const API_KEY_SCOPES: readonly ["events:read", "states:read", "streamelements:read", "tts:read", "tts:write", "subs:read", "spotify:read"];
+export type ApiKeyScope = (typeof API_KEY_SCOPES)[number];
+export declare function isApiKeyScope(value: unknown): value is ApiKeyScope;
+export declare function apiScopeForEvent(event: string): ApiKeyScope | null;

package/dist/api-types/chat.d.ts

@@ -0,0 +1,60 @@
+export type ChatEmoteProvider = "twitch" | "7tv" | "bttv" | "ffz";
+export type ChatEmote = {
+    provider: ChatEmoteProvider;
+    id: string;
+    name: string;
+    animated?: boolean;
+    /** Legt sich über das vorige Emote (z.B. 7TV-Hüte) */
+    zeroWidth?: boolean;
+};
+/** Badge vor dem Namen: von Twitch (Mod, Sub, ...) oder von 7TV */
+export type ChatBadge = {
+    provider: "twitch" | "7tv";
+    /** Twitch: Badge-Set, z.B. `subscriber`, `moderator` */
+    set?: string;
+    /** Twitch: Version im Set (bei Subs die Monatsstufe), 7TV: Badge-ID */
+    id: string;
+    title: string;
+    /** Bild in doppelter Größe (36 px bei Twitch) */
+    url: string;
+    /** Twitch: Zusatz, bei Subs z.B. die genauen Monate */
+    info?: string;
+};
+export type SevenTvPaintStop = {
+    at: number;
+    color: string;
+};
+export type SevenTvPaintLayer = {
+    type: "linear-gradient";
+    angle: number;
+    repeating: boolean;
+    stops: SevenTvPaintStop[];
+    opacity: number;
+} | {
+    type: "radial-gradient";
+    shape: "circle" | "ellipse";
+    repeating: boolean;
+    stops: SevenTvPaintStop[];
+    opacity: number;
+} | {
+    type: "color";
+    color: string;
+    opacity: number;
+} | {
+    type: "image";
+    url: string;
+    animated: boolean;
+    opacity: number;
+};
+export type SevenTvPaint = {
+    id: string;
+    name: string;
+    layers: SevenTvPaintLayer[];
+    /** Schatten, Versatz und Unschärfe in px */
+    shadows: Array<{
+        color: string;
+        x: number;
+        y: number;
+        blur: number;
+    }>;
+};

package/dist/api-types/device-apps.d.ts

@@ -0,0 +1,2 @@
+export declare const DEVICE_APP_SCOPES: readonly ["spotify"];
+export type DeviceAppScope = (typeof DEVICE_APP_SCOPES)[number];

package/dist/api-types/events.d.ts

@@ -0,0 +1,17 @@
+export type TwitchEventType = "stream.online" | "stream.offline" | "twitch.follow" | "twitch.sub" | "twitch.sub_gift" | "twitch.cheer" | "twitch.raid" | "twitch.channel_point" | "twitch.poll_started" | "twitch.poll_progress" | "twitch.poll_ended" | "twitch.prediction_started" | "twitch.prediction_progress" | "twitch.prediction_locked" | "twitch.prediction_ended" | "twitch.channel_point_resolved" | "twitch.power_up" | "twitch.channel_updated" | "twitch.title_changed" | "twitch.category_changed" | "twitch.ban" | "twitch.unban" | "twitch.vip_added" | "twitch.vip_removed" | "twitch.moderator_added" | "twitch.moderator_removed" | "twitch.hype_train_started" | "twitch.hype_train_progress" | "twitch.hype_train_ended" | "twitch.goal_started" | "twitch.goal_progress" | "twitch.goal_ended" | "twitch.charity_started" | "twitch.charity_progress" | "twitch.charity_donated" | "twitch.charity_stopped" | "twitch.ad_break" | "twitch.watch_streak" | "twitch.shoutout_sent" | "twitch.modiversary" | "twitch.chat_message" | "twitch.chat_cleared" | "twitch.chat_user_cleared" | "twitch.chat_message_deleted" | "twitch.chat_settings_updated" | "twitch.chat_message_held" | "twitch.chat_message_held_updated" | "twitch.shared_chat_started" | "twitch.shared_chat_updated" | "twitch.shared_chat_ended" | "twitch.guest_star_session_started" | "twitch.guest_star_session_ended" | "twitch.guest_star_guest_updated" | "twitch.guest_star_settings_updated";
+export type StreamElementsEventType = "streamelements.tip";
+export type EventlogEventType = TwitchEventType | StreamElementsEventType;
+/** Was ein Client über den Live-Stream bekommen kann (je nach Scopes des Schlüssels) */
+export type OrgEventType = TwitchEventType | StreamElementsEventType | "state.updated" | "state.snapshot" | "api_key.revoked" | "tts.ready" | "tts.skip" | "tts.clear" | "subs.updated" | "spotify.now_playing";
+/**
+ * Ein Event des Kanals. `E` erweitert der Server um Events, die nie bei Clients ankommen
+ * (Dashboard, interne Signale, siehe OrgEvent in @pixl/types).
+ */
+export type OrgEvent<E extends string = OrgEventType> = {
+    orgId: string;
+    event: E;
+    data: Record<string, unknown>;
+    id?: string;
+    at?: string;
+    replay?: boolean;
+};

package/dist/api-types/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./events.js";
+export * from "./chat.js";
+export * from "./spotify.js";
+export * from "./api-scopes.js";
+export * from "./streamelements.js";
+export * from "./tts.js";
+export * from "./modules.js";
+export * from "./device-apps.js";

package/dist/api-types/modules.d.ts

@@ -0,0 +1,4 @@
+export declare const CHANNEL_MODULES: readonly ["music", "tts"];
+export type ChannelModule = (typeof CHANNEL_MODULES)[number];
+/** Fehlercode in API-Antworten, wenn das Modul aus ist */
+export declare const MODULE_DISABLED_CODE = "module_disabled";

package/dist/api-types/spotify.d.ts

@@ -0,0 +1,108 @@
+export type SpotifyTrack = {
+    uri: string;
+    name: string;
+    artists: string[];
+    album: string;
+    /** Kleinstes Cover mit mindestens 64px, sonst das kleinste vorhandene */
+    image: string | null;
+    durationMs: number;
+    explicit: boolean;
+    /** Link zum Track bei Spotify */
+    url: string | null;
+};
+export type SpotifyPlayback = {
+    isPlaying: boolean;
+    progressMs: number;
+    track: SpotifyTrack | null;
+    device: {
+        name: string;
+        type: string;
+        volume: number | null;
+        supportsVolume: boolean;
+    } | null;
+    /** Was Spotify gerade nicht zulässt (z.B. während Werbung, oder Pause, wenn schon pausiert) */
+    disallows: {
+        pause: boolean;
+        resume: boolean;
+        next: boolean;
+        previous: boolean;
+    };
+};
+/** Eintrag der Warteschlange, ergänzt um den pixl-Nutzer, der ihn hinzugefügt hat */
+export type SpotifyQueueItem = SpotifyTrack & {
+    addedBy: {
+        name: string;
+        image: string | null;
+    } | null;
+};
+/** Warum Spotify gerade nicht kann. Der Server liefert den Grund, die UI den Text. */
+export type SpotifyProblem = "not_connected" | "reconnect" | "no_device" | "premium" | "restricted" | "offline" | "rate_limited" | "unavailable";
+export type SpotifyState = {
+    problem: SpotifyProblem | null;
+    playback: SpotifyPlayback | null;
+    /** Wer den laufenden Song über pixl hinzugefügt hat */
+    currentAddedBy: SpotifyQueueItem["addedBy"];
+    queue: SpotifyQueueItem[];
+    /** Ob der Twitch-Kanal live ist. Offline dürfen nur Owner Spotify sehen und steuern, außer allowOffline ist an. */
+    channelLive: boolean;
+    /** Owner-Einstellung: Mitglieder dürfen auch offline steuern (Standard aus) */
+    allowOffline: boolean;
+};
+/**
+ * Was gerade läuft, für Widgets (/api/v1/spotify/now-playing, Event spotify.now_playing).
+ * Bewusst schlank: kein Gerät, keine Queue. progressMs gilt zum Zeitpunkt at, solange
+ * playing an ist, rechnet das Widget selbst weiter.
+ */
+export type SpotifyNowPlaying = {
+    playing: boolean;
+    progressMs: number;
+    /** ISO-Zeit, zu der progressMs gemessen wurde */
+    at: string;
+    /** null = nichts geladen, kein Gerät aktiv */
+    track: SpotifyTrack | null;
+    /** Wer den Song über pixl in die Queue gelegt hat */
+    addedBy: {
+        name: string;
+    } | null;
+};
+/** Belohnungen, die pixl bei Twitch anlegt: Song wünschen, überspringen, letzten nochmal */
+export declare const SPOTIFY_REWARD_KINDS: readonly ["request", "skip", "previous"];
+export type SpotifyRewardKind = (typeof SPOTIFY_REWARD_KINDS)[number];
+export declare function isSpotifyRewardKind(value: unknown): value is SpotifyRewardKind;
+/** pending = in der Prüfliste, queued = an Spotify geschickt, played = lief bzw. ausgeführt, refunded = Punkte zurück */
+export type SpotifyRequestStatus = "pending" | "queued" | "played" | "refunded";
+/** Warum eine Einlösung erstattet wurde */
+export type SpotifyRequestReason = "not_found" | "not_track" | "blocked" | "no_music" | "too_long" | "explicit" | "repeat" | "already_queued" | "manual" | "expired" | "stream_ended" | "error";
+export type SpotifyRequest = {
+    id: string;
+    kind: SpotifyRewardKind;
+    /** Twitch-Name des Zuschauers */
+    viewer: string;
+    /** Was der Zuschauer eingegeben hat (nur bei Wünschen) */
+    input: string;
+    /** Gewünschter bzw. übersprungener Song */
+    track: SpotifyTrack | null;
+    status: SpotifyRequestStatus;
+    /** Warum erstattet, null = ohne Grund (in Twitch storniert, Belohnung entfernt) */
+    reason: SpotifyRequestReason | null;
+    createdAt: string;
+    /** Alles Gespeicherte für den Detail-Dialog (Fehlersuche, z.B. falscher Song erkannt) */
+    redemptionId: string;
+    rewardId: string;
+    viewerId: string;
+    viewerLogin: string;
+    trackUri: string | null;
+    queuedAt: string | null;
+    finishedAt: string | null;
+};
+/** Kurzer Stand der Musik-Belohnungen, z.B. für die Stream-Deck-Taste */
+export type SpotifyRequestsSummary = {
+    /** Mindestens eine Belohnung ist an und bei Twitch angelegt */
+    active: boolean;
+    /** Von Hand pausiert bis, null = nicht. Weit in der Zukunft = bis zum Fortsetzen */
+    pausedUntil: string | null;
+    /** Pausiert, weil der Kanal offline ist */
+    pausedOffline: boolean;
+    /** Wünsche in der Warteschlange, die noch nicht gelaufen sind */
+    queued: number;
+};

package/dist/api-types/streamelements.d.ts

@@ -0,0 +1,3 @@
+export declare const STREAMELEMENTS_PROXY_PATHS: readonly ["activities", "sessions", "tips/leaderboard", "points/top", "points/alltime", "store/items", "contests", "songrequest/queue", "songrequest/playing"];
+export type StreamElementsProxyPath = (typeof STREAMELEMENTS_PROXY_PATHS)[number];
+export declare function isStreamElementsProxyPath(value: unknown): value is StreamElementsProxyPath;

package/dist/api-types/tts.d.ts

@@ -0,0 +1,27 @@
+export declare const TTS_MAX_CHARS = 3000;
+/** Warum nichts vorgelesen wird. Der Server liefert den Grund, die UI den Text. */
+export type TtsProblem = "not_configured" | "disabled" | "quota" | "global_limit" | "blocked" | "empty" | "unknown_voice" | "unavailable";
+/**
+ * Welche Filter ein eigener Aufruf (SDK `speak()`, `POST /api/v1/tts`) anwendet.
+ * Alles ist standardmäßig an. Unsichtbare Zeichen und die Längengrenze gelten immer.
+ */
+export type TtsFilters = {
+    /** Links werden weggelassen */
+    links?: boolean;
+    /** Wiederholungen kürzen ("HYPEEEEEE", zehnmal dasselbe Wort) */
+    repeats?: boolean;
+    /** Gesperrte Wörter des Kanals: Text wird abgelehnt */
+    blockedWords?: boolean;
+};
+export declare const TTS_FILTER_KEYS: readonly ["links", "repeats", "blockedWords"];
+/**
+ * Zeitmarke eines Wortes im Audio, in Millisekunden ab Start. Gemeinsames Format
+ * für alle Anbieter (Polly: Speech Marks, Fish: Timestamps). `end` fehlt, wenn der
+ * Anbieter nur Startzeiten kennt, dann gilt der Start des nächsten Wortes bzw. das
+ * Ende des Audios.
+ */
+export type TtsMark = {
+    word: string;
+    start: number;
+    end: number | null;
+};

package/dist/chat.d.ts

@@ -0,0 +1,53 @@
+import type { ChatBadge, ChatEmote, SevenTvPaint } from "./api-types/index.js";
+import type { Pixl } from "./client.js";
+export type EmoteSize = 1 | 2 | 4;
+/** Bild-URL eines Emotes. `size` 1, 2 oder 4 (Twitch und BTTV liefern bei 4 die größte Stufe). */
+export declare function emoteUrl(emote: ChatEmote, size?: EmoteSize): string;
+export declare function escapeHtml(text: string): string;
+export type ChatHtmlOptions = {
+    /** Bildgröße der Emotes (Standard 2, wirkt scharf bei normaler Schriftgröße) */
+    size?: EmoteSize;
+};
+/**
+ * HTML einer Chat-Nachricht. Emotes als `<img class="pixl-emote">`, zero-width Emotes
+ * zusammen mit dem Emote davor in `<span class="pixl-emote-stack">`.
+ */
+export declare function chatHtml(text: string, emotes?: Record<string, ChatEmote>, options?: ChatHtmlOptions): string;
+/** Badges einer Nachricht (`data.badges`) als `<img class="pixl-badge">`, Titel als `alt` */
+export declare function badgesHtml(badges?: ChatBadge[]): string;
+/**
+ * Grund-CSS für Emotes und Badges in `chatHtml`. Einmal einbinden, z.B.
+ * `document.head.append(Object.assign(document.createElement("style"), { textContent: CHAT_CSS }))`.
+ */
+export declare const CHAT_CSS = ".pixl-emote{height:1.75em;vertical-align:middle;margin:-.25em 0}\n.pixl-emote-stack{display:inline-grid;vertical-align:middle}\n.pixl-emote-stack>.pixl-emote{grid-area:1/1;justify-self:center;align-self:center;margin:0}\n.pixl-badge{height:1.1em;vertical-align:middle;margin-right:.25em}";
+/**
+ * CSS für einen Namen mit 7TV-Paint, als Inline-Style. Setzt den Verlauf als
+ * Hintergrund und schneidet ihn auf den Text zu. `fallback` = Farbe, falls der
+ * Browser das nicht kann (z.B. die Twitch-Farbe des Users).
+ */
+export declare function paintCss(paint: SevenTvPaint, fallback?: string): string;
+/** Chat-Helfer an `pixl.chat` */
+export declare class PixlChat {
+    private readonly pixl;
+    private paints;
+    private queue;
+    private timer;
+    constructor(pixl: Pixl);
+    /** Grund-CSS für Emotes im HTML (siehe `CHAT_CSS`) */
+    readonly css = ".pixl-emote{height:1.75em;vertical-align:middle;margin:-.25em 0}\n.pixl-emote-stack{display:inline-grid;vertical-align:middle}\n.pixl-emote-stack>.pixl-emote{grid-area:1/1;justify-self:center;align-self:center;margin:0}\n.pixl-badge{height:1.1em;vertical-align:middle;margin-right:.25em}";
+    /** Bild-URL eines Emotes */
+    emoteUrl(emote: ChatEmote, size?: EmoteSize): string;
+    /** Badges als HTML (siehe `badgesHtml`) */
+    badgesHtml(badges?: ChatBadge[]): string;
+    /** CSS für einen Namen mit 7TV-Paint (siehe `paintCss`) */
+    paintCss(paint: SevenTvPaint, fallback?: string): string;
+    /** HTML einer Nachricht (dasselbe wie `data.html` bei `twitch.chat_message`) */
+    html(text: string, emotes?: Record<string, ChatEmote>, options?: ChatHtmlOptions): string;
+    /** Alle Emotes des Kanals (7TV, BTTV, FFZ, Kanal und global), Gewinner bei gleichem Namen zuerst */
+    emotes(): Promise<ChatEmote[]>;
+    /** Definition eines 7TV-Paints (`data.paint` bei `twitch.chat_message`). Gecacht, mehrere Abfragen werden gebündelt. */
+    paint(id: string): Promise<SevenTvPaint | null>;
+    /** Inline-Style für einen Namen mit Paint, `fallback` wenn es keinen gibt */
+    paintStyle(id: string | null | undefined, fallback?: string): Promise<string>;
+    private flush;
+}

package/dist/client.d.ts

@@ -0,0 +1,194 @@
+import type { SpotifyNowPlaying, StreamElementsProxyPath } from "./api-types/index.js";
+import { PixlChat } from "./chat.js";
+import { EventFeed, type FeedOptions } from "./feed.js";
+import { PixlTts } from "./tts.js";
+export type PixlStatus = "connecting" | "connected" | "disconnected" | "unauthorized" | "closed";
+export type PixlOptions = {
+    /** API-Schlüssel (`pixl_…`), erstellt unter Einstellungen → API-Schlüssel */
+    key: string;
+    /**
+     * Adresse der pixl-Instanz. Standard: der Server, von dem das SDK-Script
+     * geladen wurde, sonst https://pixl.lennox.zip
+     */
+    baseUrl?: string;
+    /** Stream automatisch verbinden (Standard: true). Sonst manuell per connect(). */
+    autoConnect?: boolean;
+    /**
+     * Abbruch und Neuverbinden der Live-Verbindung in der Browser-Konsole melden
+     * (Standard: true). Nur Wechsel, keine Events.
+     */
+    logs?: boolean;
+};
+export type PixlEvent = {
+    /** Event-Typ, z.B. `twitch.cheer` */
+    event: string;
+    /** Payload laut Event-Referenz */
+    data: Record<string, unknown>;
+    /** true bei erneut abgespielten Events aus dem Eventlog */
+    replay: boolean;
+    /** ID der Eventlog-Zeile (nur bei Events, die im Eventlog stehen) */
+    id?: string;
+    /** Zeitpunkt als ISO-String (nur bei Events, die im Eventlog stehen) */
+    at?: string;
+    /** true, wenn das Event aus der Historie nachgeladen wurde (nur bei feed()) */
+    history?: boolean;
+};
+export type EventHandler = (data: Record<string, unknown>, event: PixlEvent) => void;
+export type StateHandler = (value: unknown, key: string) => void;
+export type EventsQuery = {
+    /** Ab wann: Date, ISO-String, Unix-ms oder `"stream"` (Start des letzten Streams) */
+    since?: Date | string | number;
+    /** Bis wann (exklusiv) */
+    until?: Date | string | number;
+    /** Nur diese Event-Typen */
+    types?: string[];
+    /** Max. Anzahl pro Seite, 1 bis 200 (Standard 50) */
+    limit?: number;
+    /** `nextCursor` der vorherigen Seite */
+    cursor?: string;
+};
+export type EventsPage = {
+    events: {
+        id: string;
+        event: string;
+        data: Record<string, unknown>;
+        at: string;
+    }[];
+    nextCursor: string | null;
+};
+export type OrgInfo = {
+    id: string;
+    name: string;
+    logo: string | null;
+    twitchChannelLogin: string | null;
+    /** Erlaubnisse des verwendeten Schlüssels, z.B. `["events:read"]` */
+    scopes: string[];
+};
+export type SubCount = {
+    /** Aktive Subs laut Twitch, inklusive des Streamers selbst (zählt Twitch so) */
+    total: number;
+    /** Sub-Punkte laut Twitch: Stufe 1 = 1, Stufe 2 = 2, Stufe 3 = 6 */
+    points: number;
+    /** Wann pixl die Zahl bei Twitch abgefragt hat (ISO-String) */
+    at: string;
+};
+export declare class PixlApiError extends Error {
+    status: number;
+    /** Maschinenlesbarer Grund, falls der Server einen nennt (z.B. `quota` bei TTS) */
+    problem?: string;
+    constructor(status: number, message: string, problem?: string);
+}
+export declare function toQueryDate(value: Date | string | number): string;
+export declare class Pixl {
+    /** Von global.ts gesetzt: Origin des geladenen SDK-Scripts */
+    static defaultBaseUrl: string | undefined;
+    readonly baseUrl: string;
+    private readonly key;
+    /** Text-to-Speech: vorlesen lassen und abspielen (siehe Doku "TTS") */
+    readonly tts: PixlTts;
+    /** Chat: Emotes als HTML, 7TV-Paints (siehe Doku "Chat") */
+    readonly chat: PixlChat;
+    private handlers;
+    private stateHandlers;
+    private statusHandlers;
+    private states;
+    private _status;
+    private abort;
+    private reconnectTimer;
+    private watchdog;
+    private attempt;
+    private stopped;
+    private readonly logs;
+    private everConnected;
+    private lostAt;
+    constructor(options: PixlOptions);
+    /**
+     * Handler für einen Event-Typ registrieren (`"twitch.cheer"`), oder für alle
+     * Events mit `"*"`. Gibt die Instanz zurück, Aufrufe lassen sich verketten.
+     */
+    on(event: string, handler: EventHandler): this;
+    /** Handler wieder entfernen */
+    off(event: string, handler: EventHandler): this;
+    /**
+     * State abonnieren. Der Handler läuft sofort mit dem aktuellen Wert (sobald
+     * bekannt) und danach bei jeder Änderung.
+     */
+    state(key: string, handler: StateHandler): this;
+    /** State-Handler wieder entfernen */
+    offState(key: string, handler: StateHandler): this;
+    /** Zuletzt bekannter Wert eines States (undefined, solange unbekannt) */
+    getState(key: string): unknown;
+    get status(): PixlStatus;
+    /** Statuswechsel beobachten. Gibt eine Funktion zum Abmelden zurück. */
+    onStatus(handler: (status: PixlStatus) => void): () => void;
+    private setStatus;
+    /** Rohzugriff auf einen /api/v1-Endpoint (Pfad ohne /api/v1, z.B. `/events`) */
+    request<T>(path: string, params?: Record<string, string | undefined>): Promise<T>;
+    /**
+     * Wie request(), aber mit beliebiger Methode und Body (JSON) bzw. roher
+     * Response. Für die TTS-Endpunkte, nicht Teil der öffentlichen Schnittstelle.
+     * @internal
+     */
+    _fetch(path: string, init?: {
+        method?: string;
+        json?: unknown;
+    }): Promise<Response>;
+    /** Eventlog abfragen (neueste zuerst, seitenweise) */
+    events(query?: EventsQuery): Promise<EventsPage>;
+    /** Infos zur Organisation, der der Schlüssel gehört, plus dessen Scopes */
+    org(): Promise<OrgInfo>;
+    /**
+     * Aktuelle Sub-Zahl direkt von Twitch, unabhängig vom Eventlog (höchstens 60 s alt).
+     * Braucht einen Schlüssel mit `subs:read`. Änderungen kommen live als `subs.updated`
+     * mit denselben Feldern.
+     */
+    subs(): Promise<SubCount>;
+    /**
+     * Was gerade auf Spotify läuft: `{ playing, progressMs, at, track, addedBy }`.
+     * Braucht einen Schlüssel mit `spotify:read` und das Modul Musik. Läuft nichts
+     * (kein Gerät aktiv), ist `track` null. Änderungen (anderer Song, Play/Pause,
+     * Sprung im Song) kommen live als `spotify.now_playing` mit denselben Feldern.
+     * Den laufenden Fortschritt liefert `Pixl.progress(nowPlaying)`.
+     */
+    nowPlaying(): Promise<SpotifyNowPlaying>;
+    /**
+     * Fortschritt in ms zum Zeitpunkt `now`, aus einer Messung von `nowPlaying()` bzw.
+     * `spotify.now_playing`. Läuft der Song, wird ab `at` weitergerechnet, höchstens bis
+     * zur Songlänge.
+     */
+    static progress(nowPlaying: SpotifyNowPlaying, now?: number): number;
+    /**
+     * Lesender Zugriff auf den verbundenen StreamElements-Kanal, pixl reicht die
+     * Anfrage mit dem hinterlegten Overlay Token weiter (der Token bleibt bei pixl).
+     * Braucht einen Schlüssel mit `streamelements:read`. `params` gehen 1:1 als
+     * Query-Parameter an StreamElements, die Antwort kommt unverändert zurück.
+     */
+    streamElements<T = unknown>(path: StreamElementsProxyPath, params?: Record<string, string | number | undefined>): Promise<T>;
+    /** Aktuelle Werte aller States */
+    fetchStates(): Promise<Record<string, unknown>>;
+    /**
+     * Alle Events seit `since` holen, über alle Seiten hinweg, älteste zuerst.
+     * Für große Zeiträume entsprechend viele Requests (200 Events pro Seite).
+     */
+    fetchAllEvents(query?: Omit<EventsQuery, "cursor" | "limit">): Promise<EventsPage["events"]>;
+    /**
+     * Historie + live in einem: `handler` bekommt erst alle Events seit `since`
+     * (älteste zuerst, `event.history === true`), danach jedes neue live. Jedes
+     * Event kommt genau einmal an, auch über Verbindungsabbrüche hinweg.
+     * Rechnet selbst nichts, Summen o.ä. baut der Aufrufer im Handler.
+     */
+    feed(options: FeedOptions, handler: EventHandler): EventFeed;
+    /** Live-Stream verbinden (passiert standardmäßig automatisch) */
+    connect(): void;
+    /** Stream trennen und nicht neu verbinden */
+    disconnect(): void;
+    private run;
+    private log;
+    private scheduleReconnect;
+    private armWatchdog;
+    private clearWatchdog;
+    private readStream;
+    private dispatch;
+    private emit;
+    private setState;
+}

package/dist/feed.d.ts

@@ -0,0 +1,57 @@
+import type { EventHandler, Pixl } from "./client.js";
+export type FeedOptions = {
+    /**
+     * Ab wann die Historie geladen wird: Date, ISO-String, Unix-ms oder `"stream"`
+     * (Start des letzten Streams). Pflicht, damit nicht versehentlich das
+     * komplette Eventlog geladen wird.
+     */
+    since: Date | string | number;
+    /** Nur diese Event-Typen (Historie und live) */
+    types?: string[];
+};
+/**
+ * Historie + live, jedes Event genau einmal. Ablauf bei jedem (Re-)Connect:
+ * 1. Live-Events ab jetzt puffern (der Stream steht bereits)
+ * 2. Historie seit `since` laden und ausliefern, was noch nicht ausgeliefert ist
+ * 3. Puffer abarbeiten, Doppelte (gleiche ID) überspringen, danach direkt live
+ * Weil nach jedem Reconnect die Historie erneut abgeglichen wird, gehen auch
+ * Events aus einer Verbindungslücke nicht verloren. Nach dem ersten Laden reichen
+ * dafür die neuesten Seiten: geblättert wird nur bis kurz vor das neueste schon
+ * ausgelieferte Event. Sonst lüde jedes Overlay nach einem Deploy die komplette
+ * Historie seit `since` neu und liefe dabei ins Rate-Limit.
+ * Schlägt das Laden fehl, wird es mit Backoff wiederholt, solange der Stream steht.
+ *
+ * Bewusst ohne jede Auswertung: was der Handler mit den Events macht (Summen,
+ * Listen, Alerts), entscheidet der Aufrufer.
+ */
+export declare class EventFeed {
+    /** true, sobald die Historie einmal komplett ausgeliefert wurde */
+    ready: boolean;
+    /** Letzter Fehler beim Laden der Historie */
+    error: Error | null;
+    private readonly pixl;
+    private readonly since;
+    private readonly types;
+    private readonly handler;
+    private readonly delivered;
+    private readonly errorListeners;
+    private buffer;
+    private loadSeq;
+    private stopped;
+    private latestAt;
+    private retryTimer;
+    private retryAttempt;
+    private readonly unsubscribeStatus;
+    private readonly onEvent;
+    constructor(pixl: Pixl, options: FeedOptions, handler: EventHandler);
+    /** Fehler beim Laden der Historie beobachten (z.B. noch nie gestreamt bei since="stream") */
+    onError(listener: (error: Error) => void): () => void;
+    /** Feed beenden, der Handler wird danach nicht mehr aufgerufen */
+    stop(): void;
+    private load;
+    private fetchHistory;
+    private scheduleRetry;
+    private clearRetry;
+    private handleLive;
+    private deliver;
+}