@pixl-app/sdk 0.1.1 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 1.0.0
+
+Neu geschrieben, bricht bestehende Widgets. Wer 0.1 braucht, bindet es mit fester Version über jsDelivr ein (`@pixl-app/sdk@0.1.1`).
+
+- Spricht Protokoll 2: einheitliche Payloads (Personen als `user` mit ID, Login, Name und Avatar, Geld als `{ value, currency }`, `count` statt `amount`, `viewers` statt `viewerCount`), Chat-Nachrichten mit fertigem `html`.
+- Handler bekommen ein Event-Objekt `{ type, data, id, at, source }` mit Typen pro Event, `on()` gibt eine Funktion zum Abmelden zurück.
+- Live-Werte mit `value` und `subscribe()`: `status`, `channel`, `twitch.subs`, `twitch.hypeTrain`, `twitch.poll`, `twitch.prediction`, `twitch.goal`, `twitch.charity`, `twitch.adBreak`, `spotify.nowPlaying`.
+- `await pixl.ready`, Fehler als `PixlError` mit festem `code`.
+- Historie unter `pixl.events`: `list()` (blättert selbst), `all()`, `feed()`.
+- `pixl.sendTestEvent(type, felder)` und Demo-Modus (`new Pixl({ demo: true })`) mit einer Vorlage pro Event-Typ.
+- Gehostete Widgets: `pixl.widget()` mit `settings` und `values` als Live-Werte, Änderungen per `set`, `add`, `batch` und Listen-Operationen, Uploads über `files`. Auf Steuer-Seiten kommt der Zugang vom Dashboard.
+- Schriften: `font`-Felder lädt `pixl.widget()` von selbst, von Bunny Fonts (dieselben Schriften wie Google Fonts, ohne dass Google die IP-Adresse bekommt). Dazu `Pixl.fontFamily(name)` für den CSS-Wert und `Pixl.loadFont(name)` für feste Schriften, über npm als `fontFamily` und `loadFont`. `<pixl-field>` schlägt für Schriften beliebte Google Fonts vor.
+- Fertige Bausteine für Steuer-Seiten im Stil von pixl unter `@pixl-app/sdk/ui` bzw. `/sdk/pixl-ui.js`: `<pixl-field>` (mit Kurzformen wie `<pixl-toggle>`), `<pixl-list>`, `<pixl-dialog>`, `<pixl-section>`, dazu `<pixl-dropdown>` (Auswahl mit eigener Liste statt der des Systems, auch in Feldern und Listen) und `<pixl-checkbox>`. Klassen für eigene Elemente: `pixl-btn`, `pixl-input`, `pixl-checkbox`, `pixl-select` (nur als Rückfall), `pixl-card`. Höhe und Farben des Dashboards gelten auch für Seiten ohne eigenes `Pixl`-Objekt.
+- Gehostete Widgets ohne eigenen Code: Felder stehen als CSS-Variablen auf `<html>` (`accentColor` → `--pixl-accent-color`, Texte für `content`, Schalter als 1 oder 0, Dateien als `url(…)`). Ohne `new Pixl()` verbindet das SDK dann selbst.
+- `pixl.fields` (auch `widget.fields`): alle Felder als einfaches Objekt, immer aktuell, Steuerelemente vor Einstellungen, z.B. `const { text, color } = pixl.fields`.
+- `<pixl-field>` zeigt geheime Einstellungen (`sensitive`) verdeckt mit Auge und kennt Stimmen (`voice`) als Auswahl. Dazu `widget.voices()` für eigene Steuer-Seiten, ohne `tts:read`.
+- In der Vorschau im Dashboard gelten Werte, die das Widget selbst setzt, nur dort, die Felder kommen aus dem gespeicherten Entwurf.
+- `tts.speak()` liest in der Vorschau in pixl nur dort vor, der Player der Vorschau spielt es ab. Beim Bedienen mit verbundener Browserquelle liest die vor, die Vorschau spielt es mit ab und `speak()` wirft dort einen `PixlError` mit `problem: "preview"`.
+- Weggefallen: States (`state()`, `getState()`, `fetchStates()`), `org()` (jetzt `channel`), `nowPlaying()` und `Pixl.progress()` (jetzt `spotify.nowPlaying` und `spotify.progress()`), `subs()` (jetzt `twitch.subs`), `streamElements()` (jetzt `streamElements.get()`), `onStatus()` (jetzt `status.subscribe()`), `PixlApiError` (jetzt `PixlError`).
+
 ## 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.

package/README.md

@@ -12,7 +12,7 @@ Per Script-Tag, ohne Installation:
 <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`));
+	pixl.on("twitch.follow", (e) => console.log(`${e.data.user.name} folgt jetzt`));
 </script>
 ```
 
@@ -32,7 +32,12 @@ bun add @pixl-app/sdk   # oder: npm i @pixl-app/sdk
 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`));
+pixl.on("twitch.follow", (e) => console.log(`${e.data.user.name} folgt jetzt`));
+pixl.twitch.subs.subscribe((subs) => console.log(`${subs?.total ?? "?"} Subs`));
+
+// Ohne Schlüssel ausprobieren: Demo-Modus mit Vorlagen
+const demo = new Pixl({ demo: true });
+demo.sendTestEvent("twitch.raid", { viewers: 50 });
 ```
 
 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).
@@ -52,7 +57,7 @@ Ein Overlay mit dem Dev-SDK testen: `<script src="http://localhost:4400/pixl.js"
 
 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" })`.
+Gegen eine lokale pixl-Instanz: `new Pixl({ key, baseUrl: "http://localhost:5173" })`. Version 1 braucht einen pixl-Server mit Protokoll 2 (`/api/v1/stream?v=2`).
 
 ## Versionen und Releases
 

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

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

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

@@ -6,3 +6,6 @@ export * from "./streamelements.js";
 export * from "./tts.js";
 export * from "./modules.js";
 export * from "./device-apps.js";
+export * from "./payloads.js";
+export * from "./templates.js";
+export * from "./widgets.js";

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

@@ -1,4 +1,4 @@
-export declare const CHANNEL_MODULES: readonly ["music", "tts"];
+export declare const CHANNEL_MODULES: readonly ["music", "tts", "widgets"];
 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/payloads.d.ts

@@ -0,0 +1,389 @@
+import type { ChatBadge, ChatEmote } from "./chat.js";
+import type { SpotifyNowPlaying } from "./spotify.js";
+import type { StreamWidgetMessage, WidgetState } from "./widgets.js";
+/** Eine Person auf Twitch */
+export type User = {
+    /** Twitch-ID. null nur bei alten Einträgen aus der Historie, die pixl nicht mehr zuordnen kann */
+    id: string | null;
+    /** Login, klein geschrieben */
+    login: string;
+    /** Anzeigename */
+    name: string;
+    /** Profilbild, null wenn Twitch keins liefert */
+    avatar: string | null;
+};
+/** Geldbetrag, immer als Dezimalzahl (4.2 = 4,20) */
+export type Money = {
+    value: number;
+    currency: string;
+};
+/** Sub-Stufe. Prime zählt bei Twitch als Stufe 1, steht hier aber eigens */
+export type Tier = "prime" | "1" | "2" | "3";
+/** Woher ein Event kommt */
+export type ChannelEventSource = "live" | "history" | "replay" | "test";
+export type PollChoice = {
+    title: string;
+    votes: number;
+};
+export type PredictionOutcome = {
+    title: string;
+    points: number;
+};
+export type HypeTrain = {
+    level: number;
+    /** Fortschritt im aktuellen Level und Ziel des Levels */
+    progress: number;
+    goal: number;
+    /** Summe aller Beiträge */
+    total: number;
+    /** Wann der Zug ohne weitere Beiträge endet, ISO */
+    expiresAt: string | null;
+    startedAt: string | null;
+    /** `regular`, `golden_kappa` oder `treasure` */
+    type: string;
+    /** Geteilter Zug mehrerer Kanäle */
+    shared: boolean;
+    participants: {
+        login: string;
+        name: string;
+    }[];
+    topContributions: {
+        user: User;
+        type: "bits" | "subscription" | "other";
+        total: number;
+    }[];
+    /** Rekord des Kanals, nur beim Start bekannt */
+    record: {
+        level: number;
+        total: number;
+    } | null;
+};
+/** Payload jedes Events, das bei Clients ankommen kann */
+export type EventPayloads = {
+    "stream.online": {
+        streamId: string;
+        title: string | null;
+        category: string | null;
+        url: string;
+        thumbnailUrl: string | null;
+    };
+    "stream.offline": {
+        durationSec: number | null;
+    };
+    "twitch.follow": {
+        user: User;
+    };
+    "twitch.sub": {
+        user: User;
+        tier: Tier;
+        /** Monate insgesamt, 1 bei einem neuen Sub */
+        months: number;
+        /** Monate am Stück, null wenn die Person sie nicht teilt */
+        streak: number | null;
+        /** Im Voraus bezahlte Monate */
+        durationMonths: number;
+        message: string | null;
+    };
+    "twitch.sub_gift": {
+        /** null = anonym */
+        user: User | null;
+        tier: Tier;
+        /** Anzahl verschenkter Subs */
+        count: number;
+        /** An zufällige Zuschauer (Gift-Bombe) statt an eine Person */
+        community: boolean;
+        /** Geschenkte Monate pro Empfänger (Gift-Bomben immer 1) */
+        months: number;
+        /** Empfänger. Bei Gift-Bomben live noch leer, in der Historie nach ein paar Sekunden vollständig */
+        recipients: User[];
+        /** Alle bisher verschenkten Subs der Person, null wenn anonym oder unbekannt */
+        totalGifted: number | null;
+    };
+    "twitch.cheer": {
+        user: User | null;
+        bits: number;
+        message: string | null;
+    };
+    "twitch.raid": {
+        user: User;
+        viewers: number;
+    };
+    "twitch.channel_point": {
+        user: User;
+        reward: string;
+        cost: number;
+        input: string | null;
+    };
+    "twitch.channel_point_resolved": {
+        user: User;
+        reward: string;
+        status: "fulfilled" | "canceled";
+    };
+    "twitch.power_up": {
+        user: User;
+        title: string;
+        bits: number;
+        input: string | null;
+    };
+    "twitch.watch_streak": {
+        user: User;
+        streak: number;
+        channelPoints: number;
+    };
+    "twitch.modiversary": {
+        user: User;
+        months: number;
+    };
+    "twitch.shoutout_sent": {
+        user: User;
+        viewers: number;
+    };
+    "twitch.poll_started": {
+        title: string;
+        choices: PollChoice[];
+    };
+    "twitch.poll_progress": {
+        title: string;
+        choices: PollChoice[];
+    };
+    "twitch.poll_ended": {
+        title: string;
+        status: "completed" | "archived" | "terminated";
+        choices: PollChoice[];
+    };
+    "twitch.prediction_started": {
+        title: string;
+        outcomes: PredictionOutcome[];
+    };
+    "twitch.prediction_progress": {
+        title: string;
+        outcomes: PredictionOutcome[];
+    };
+    "twitch.prediction_locked": {
+        title: string;
+        outcomes: PredictionOutcome[];
+    };
+    "twitch.prediction_ended": {
+        title: string;
+        status: "resolved" | "canceled";
+        /** Titel des Gewinners, null wenn abgebrochen */
+        winner: string | null;
+        outcomes: PredictionOutcome[];
+    };
+    "twitch.hype_train_started": HypeTrain;
+    "twitch.hype_train_progress": HypeTrain;
+    "twitch.hype_train_ended": HypeTrain;
+    "twitch.goal_started": {
+        type: string;
+        description: string;
+        current: number;
+        target: number;
+    };
+    "twitch.goal_progress": {
+        current: number;
+        target: number;
+    };
+    "twitch.goal_ended": {
+        type: string;
+        description: string;
+        current: number;
+        target: number;
+        achieved: boolean;
+    };
+    "twitch.charity_started": {
+        charity: string;
+        target: Money;
+    };
+    "twitch.charity_progress": {
+        current: Money;
+        target: Money;
+    };
+    "twitch.charity_donated": {
+        user: User;
+        charity: string;
+        amount: Money;
+    };
+    "twitch.charity_stopped": {
+        charity: string;
+        current: Money;
+        target: Money;
+    };
+    "twitch.ad_break": {
+        durationSec: number;
+        automatic: boolean;
+        startedAt: string | null;
+    };
+    "twitch.title_changed": {
+        title: string;
+    };
+    "twitch.category_changed": {
+        category: string;
+    };
+    "twitch.ban": {
+        user: User;
+        moderator: User | null;
+        reason: string | null;
+        permanent: boolean;
+        endsAt: string | null;
+    };
+    "twitch.unban": {
+        user: User;
+        moderator: User | null;
+    };
+    "twitch.vip_added": {
+        user: User;
+    };
+    "twitch.vip_removed": {
+        user: User;
+    };
+    "twitch.moderator_added": {
+        user: User;
+    };
+    "twitch.moderator_removed": {
+        user: User;
+    };
+    "twitch.chat_message": {
+        user: User;
+        messageId: string;
+        text: string;
+        /** Fertiges HTML mit Emotes, Text ist escaped */
+        html: string;
+        color: string | null;
+        emotes: Record<string, ChatEmote>;
+        badges: ChatBadge[];
+        /** ID des 7TV-Paints, Definition über `pixl.chat.paint(id)` */
+        paint: string | null;
+    };
+    "twitch.chat_cleared": Record<string, never>;
+    "twitch.chat_user_cleared": {
+        user: User;
+    };
+    "twitch.chat_message_deleted": {
+        user: User;
+        messageId: string;
+    };
+    "twitch.chat_settings_updated": {
+        emoteMode: boolean;
+        followerMode: boolean;
+        followerModeDuration: number | null;
+        slowMode: boolean;
+        slowModeWait: number | null;
+        subscriberMode: boolean;
+        uniqueChatMode: boolean;
+    };
+    "twitch.chat_message_held": {
+        user: User;
+        text: string;
+        messageId: string;
+    };
+    "twitch.chat_message_held_updated": {
+        user: User;
+        status: string;
+        messageId: string;
+    };
+    "twitch.shared_chat_started": {
+        sessionId: string;
+        participants: number;
+    };
+    "twitch.shared_chat_updated": {
+        sessionId: string;
+        participants: number;
+    };
+    "twitch.shared_chat_ended": {
+        sessionId: string;
+    };
+    "twitch.guest_star_session_started": {
+        sessionId: string;
+    };
+    "twitch.guest_star_session_ended": {
+        sessionId: string;
+    };
+    "twitch.guest_star_guest_updated": {
+        sessionId: string;
+        user: User | null;
+        state: string;
+        slotId: string | null;
+    };
+    "twitch.guest_star_settings_updated": {
+        slotCount: number;
+        groupLayout: string;
+    };
+    "seventv.emote_added": {
+        emote: ChatEmote;
+        actor: string | null;
+    };
+    "seventv.emote_removed": {
+        emote: ChatEmote;
+        actor: string | null;
+    };
+    "seventv.emote_renamed": {
+        emote: ChatEmote;
+        oldName: string;
+        actor: string | null;
+    };
+    "seventv.emote_set_changed": {
+        setId: string;
+        name: string | null;
+        actor: string | null;
+    };
+    "streamelements.tip": {
+        /** Name, den die Person angegeben hat (kein Twitch-Login) */
+        name: string;
+        amount: Money;
+        message: string | null;
+        tipId: string;
+    };
+    "subs.updated": {
+        total: number;
+        points: number;
+        at: string;
+    };
+    "spotify.now_playing": SpotifyNowPlaying;
+    /** Audio liegt bereit, abrufbar über `/api/v1/tts/<id>/audio` */
+    "tts.ready": {
+        id: string;
+        voice: string;
+        text: string;
+        source: string;
+        eventId: string | null;
+    };
+    "tts.skip": {
+        id: string | null;
+    };
+    "tts.clear": Record<string, never>;
+};
+export type ChannelEventType = keyof EventPayloads;
+/** Ein Event, wie es bei Clients ankommt (Live-Stream ab Protokoll 2, Historie mit `v=2`) */
+export type ChannelEvent<T extends ChannelEventType = ChannelEventType> = {
+    [K in T]: {
+        type: K;
+        data: EventPayloads[K];
+        /** ID der Eventlog-Zeile, nur bei Events, die im Eventlog stehen */
+        id?: string;
+        /** Zeitpunkt, ISO */
+        at: string;
+        source: ChannelEventSource;
+    };
+}[T];
+export declare const STREAM_PROTOCOL = 2;
+/** Erste Nachricht jeder Verbindung */
+export type StreamConnected = {
+    type: "connected";
+    protocol: typeof STREAM_PROTOCOL;
+    channel: {
+        id: string;
+        name: string;
+        login: string | null;
+        avatar: string | null;
+    };
+    /** Rechte des Zugangs, z.B. `["events:read"]` */
+    scopes: string[];
+    /** Nur bei Zugängen eines gehosteten Widgets: dessen Stand */
+    widget?: WidgetState;
+};
+/** Zugang widerrufen: die Verbindung endet, nicht neu verbinden */
+export type StreamAccessRevoked = {
+    type: "access_revoked";
+};
+/** Alles, was über den Live-Stream ab Protokoll 2 kommt */
+export type StreamMessage = StreamConnected | StreamAccessRevoked | StreamWidgetMessage | ChannelEvent;

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

@@ -0,0 +1,6 @@
+import type { EventPayloads, ChannelEventType, User } from "./payloads.js";
+/** Beispiel-Person für Vorlagen */
+export declare function templateUser(name: string, id?: string): User;
+export declare const EVENT_TEMPLATES: {
+    [K in ChannelEventType]: EventPayloads[K];
+};