@zaflun/lumio-protocol 0.2.4 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,59 @@ All notable changes to `@zaflun/lumio-protocol` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.6.0
+
+### Added
+
+- **Per-extension runtime origins** — new entry point
+  `@zaflun/lumio-protocol/origin` (also re-exported from the package root) with
+  `extensionRuntimeLabel(extensionId)` (canonical lowercase UUID → 32 lowercase
+  hex, otherwise `null`), `extensionRuntimeOrigin(extensionId, template)`
+  (`https://{label}.runtime.ext.lumio.vision` → the extension's origin, `null` for an
+  invalid id or template), `extensionRuntimeOriginLabel(origin, template)` and
+  `isValidExtensionRuntimeOriginTemplate(template)`. The `/origin` entry has no
+  runtime dependencies. Additive.
+
+## 0.5.0
+
+### Added
+
+- **Kick event types** — `kick:resub`, `kick:kicks`, `kick:reward`,
+  `kick:reward_status` and `kick:stream_update` are in `LUMIO_EVENT_TYPES`,
+  `LumioEventType` and the `lumioEventTypeSchema` Zod enum. The Lumio webhook
+  receiver emits them for Kick subscription renewals, KICKs gifts, channel-point
+  redemptions (first delivery of a redemption `id` → `kick:reward`, every later
+  status change → `kick:reward_status`) and livestream metadata changes. Every
+  Kick event carries canonical top-level fields (`user_id`, `user_login`,
+  `user_name`, `avatarUrl`, `is_anonymous`) next to the original Kick payload.
+  `LUMIO_EVENT_TYPES` now holds 58 event types.
+
+  Additive: existing event strings are unchanged. Consumers that exhaustively
+  `switch` over `LumioEventType` need arms for the five new Kick types.
+
+## 0.4.0
+
+### Added
+
+- **YouTube stream lifecycle** — `youtube:stream_online` and
+  `youtube:stream_offline`, emitted by the poll-driven YouTube worker on the
+  channel-status online/offline edge (once per real transition).
+
+## 0.3.0
+
+### Removed
+
+- **Trovo event types** — `trovo:subscribe`, `trovo:spell` and `trovo:chat` are
+  gone from `LUMIO_EVENT_TYPES`, `LumioEventType` and the `lumioEventTypeSchema`
+  Zod enum. The Trovo platform has been shut down by its operator, so these
+  events can no longer be emitted. `LUMIO_EVENT_TYPES` now holds 72 event types
+  across Twitch, YouTube, Kick, Spotify, StreamElements, and per-platform +
+  cross-platform chat.
+
+  **Breaking for consumers** that reference a Trovo event type by name or
+  exhaustively `switch` over `LumioEventType`. Drop the Trovo arms; validation of
+  a Trovo event string now fails closed via `lumioEventTypeSchema`.
+
 ## 0.2.4
 
 Wire-format types for the Lumio Extension Platform — the contract for
@@ -15,7 +68,7 @@ the validated schemas.
 ### Exports
 
 - **Events** (`src/events.ts`)
-  - `LUMIO_EVENT_TYPES` — 54 platform event types across Twitch, YouTube, Kick,
+  - `LUMIO_EVENT_TYPES` — 75 platform event types across Twitch, YouTube, Kick,
     Trovo, Spotify, StreamElements, and per-platform + cross-platform chat, with
     `LumioEventType` and the `lumioEventTypeSchema` Zod enum.
   - `ACTION_TYPES` — 21 action types (Chat, OBS, Spotify, Events, Overlay), with

package/README.md

@@ -10,7 +10,7 @@ npm install @zaflun/lumio-protocol
 
 ## What's included
 
-- **54 Event Types** — Twitch, YouTube, Kick, Trovo, Spotify, StreamElements, Chat
+- **54 Event Types** — Twitch, YouTube, Kick, Spotify, StreamElements, Chat
 - **21 Action Types** — Chat, OBS, Spotify, Events, Overlay
 - **Message Schemas** — JSON-RPC 2.0 wire format (Zod validated)
 - **30 Component Types** — `LumioComponentNode` for serialized UI trees

package/dist/chunk-746VSR4E.js

@@ -0,0 +1,51 @@
+// src/origin.ts
+var EXTENSION_RUNTIME_LABEL_PLACEHOLDER = "{label}";
+var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+var LABEL_PATTERN = /^[0-9a-f]{32}$/;
+var DNS_LABEL_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+var TEMPLATE_PATTERN = /^(https:\/\/|http:\/\/)\{label\}(\.[a-z0-9.-]+(?::[0-9]{1,5})?)$/;
+function parseTemplate(template) {
+  const match = TEMPLATE_PATTERN.exec(template);
+  if (!match) return null;
+  const prefix = match[1];
+  const suffix = match[2];
+  const host = suffix.slice(1).replace(/:[0-9]+$/, "");
+  if (prefix === "http://" && host !== "localhost") return null;
+  if (!host.split(".").every((label) => DNS_LABEL_PATTERN.test(label))) return null;
+  const sample = `${prefix}${"0".repeat(32)}${suffix}`;
+  try {
+    if (new URL(sample).origin !== sample) return null;
+  } catch {
+    return null;
+  }
+  return { prefix, suffix };
+}
+function extensionRuntimeLabel(extensionId) {
+  if (typeof extensionId !== "string" || !UUID_PATTERN.test(extensionId)) return null;
+  return extensionId.replaceAll("-", "");
+}
+function extensionRuntimeOrigin(extensionId, template) {
+  const label = extensionRuntimeLabel(extensionId);
+  if (!label) return null;
+  const parsed = parseTemplate(template);
+  if (!parsed) return null;
+  return `${parsed.prefix}${label}${parsed.suffix}`;
+}
+function extensionRuntimeOriginLabel(origin, template) {
+  const parsed = parseTemplate(template);
+  if (!parsed) return null;
+  if (!origin.startsWith(parsed.prefix) || !origin.endsWith(parsed.suffix)) return null;
+  const label = origin.slice(parsed.prefix.length, origin.length - parsed.suffix.length);
+  return LABEL_PATTERN.test(label) ? label : null;
+}
+function isValidExtensionRuntimeOriginTemplate(template) {
+  return parseTemplate(template) !== null;
+}
+
+export {
+  EXTENSION_RUNTIME_LABEL_PLACEHOLDER,
+  extensionRuntimeLabel,
+  extensionRuntimeOrigin,
+  extensionRuntimeOriginLabel,
+  isValidExtensionRuntimeOriginTemplate
+};

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod/v4';
+export { EXTENSION_RUNTIME_LABEL_PLACEHOLDER, extensionRuntimeLabel, extensionRuntimeOrigin, extensionRuntimeOriginLabel, isValidExtensionRuntimeOriginTemplate } from './origin.js';
 
 declare const themeColorsSchema: z.ZodObject<{
     primary: z.ZodString;
@@ -287,7 +288,7 @@ declare const lumioMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>], "type">;
 type LumioMessage = z.infer<typeof lumioMessageSchema>;
 
-declare const LUMIO_EVENT_TYPES: readonly ["twitch:follower", "twitch:subscribe", "twitch:gift_sub", "twitch:resub", "twitch:cheer", "twitch:raid", "twitch:reward", "twitch:hype_train", "twitch:hype_train_end", "twitch:poll", "twitch:poll_end", "twitch:prediction", "twitch:prediction_lock", "twitch:prediction_end", "twitch:goal", "twitch:goal_end", "twitch:ad_break", "twitch:ban", "twitch:unban", "twitch:stream_online", "twitch:stream_offline", "twitch:stream_update", "youtube:subscribe", "youtube:member", "youtube:superchat", "youtube:supersticker", "youtube:gift_membership", "youtube:gift_membership_received", "youtube:poll", "kick:follower", "kick:subscribe", "kick:gift", "kick:stream_online", "kick:stream_offline", "trovo:subscribe", "trovo:spell", "spotify:track", "spotify:play", "spotify:pause", "spotify:skip", "spotify:volume", "spotify:queue_add", "spotify:device", "spotify:playlist_add", "spotify:playlist_remove", "spotify:playlist_create", "spotify:playlist_edit", "spotify:playlist_delete", "streamelements:tip", "twitch:chat", "youtube:chat", "kick:chat", "trovo:chat", "chat:message"];
+declare const LUMIO_EVENT_TYPES: readonly ["twitch:follower", "twitch:subscribe", "twitch:gift_sub", "twitch:resub", "twitch:cheer", "twitch:raid", "twitch:reward", "twitch:hype_train", "twitch:hype_train_end", "twitch:poll", "twitch:poll_end", "twitch:prediction", "twitch:prediction_lock", "twitch:prediction_end", "twitch:goal", "twitch:goal_end", "twitch:ad_break", "twitch:ban", "twitch:unban", "twitch:stream_online", "twitch:stream_offline", "twitch:stream_update", "youtube:subscribe", "youtube:member", "youtube:superchat", "youtube:supersticker", "youtube:gift_membership", "youtube:gift_membership_received", "youtube:poll", "youtube:stream_online", "youtube:stream_offline", "kick:follower", "kick:subscribe", "kick:resub", "kick:gift", "kick:kicks", "kick:reward", "kick:reward_status", "kick:stream_online", "kick:stream_offline", "kick:stream_update", "spotify:track", "spotify:play", "spotify:pause", "spotify:skip", "spotify:volume", "spotify:queue_add", "spotify:device", "spotify:playlist_add", "spotify:playlist_remove", "spotify:playlist_create", "spotify:playlist_edit", "spotify:playlist_delete", "streamelements:tip", "twitch:chat", "youtube:chat", "kick:chat", "chat:message"];
 type LumioEventType = (typeof LUMIO_EVENT_TYPES)[number];
 declare const lumioEventTypeSchema: z.ZodEnum<{
     "twitch:follower": "twitch:follower";
@@ -319,13 +320,18 @@ declare const lumioEventTypeSchema: z.ZodEnum<{
     "youtube:gift_membership": "youtube:gift_membership";
     "youtube:gift_membership_received": "youtube:gift_membership_received";
     "youtube:poll": "youtube:poll";
+    "youtube:stream_online": "youtube:stream_online";
+    "youtube:stream_offline": "youtube:stream_offline";
     "kick:follower": "kick:follower";
     "kick:subscribe": "kick:subscribe";
+    "kick:resub": "kick:resub";
     "kick:gift": "kick:gift";
+    "kick:kicks": "kick:kicks";
+    "kick:reward": "kick:reward";
+    "kick:reward_status": "kick:reward_status";
     "kick:stream_online": "kick:stream_online";
     "kick:stream_offline": "kick:stream_offline";
-    "trovo:subscribe": "trovo:subscribe";
-    "trovo:spell": "trovo:spell";
+    "kick:stream_update": "kick:stream_update";
     "spotify:track": "spotify:track";
     "spotify:play": "spotify:play";
     "spotify:pause": "spotify:pause";
@@ -342,7 +348,6 @@ declare const lumioEventTypeSchema: z.ZodEnum<{
     "twitch:chat": "twitch:chat";
     "youtube:chat": "youtube:chat";
     "kick:chat": "kick:chat";
-    "trovo:chat": "trovo:chat";
     "chat:message": "chat:message";
 }>;
 declare const ACTION_TYPES: readonly ["chat:send", "chat:delete", "chat:ban", "chat:unban", "chat:timeout", "obs:set_scene", "obs:set_source_visible", "obs:start_stream", "obs:stop_stream", "obs:start_recording", "obs:stop_recording", "spotify:play", "spotify:pause", "spotify:skip", "spotify:seek", "spotify:volume", "spotify:shuffle", "spotify:repeat", "spotify:queue_add", "events:emit", "overlay:update_layer"];

package/dist/index.js

@@ -1,3 +1,11 @@
+import {
+  EXTENSION_RUNTIME_LABEL_PLACEHOLDER,
+  extensionRuntimeLabel,
+  extensionRuntimeOrigin,
+  extensionRuntimeOriginLabel,
+  isValidExtensionRuntimeOriginTemplate
+} from "./chunk-746VSR4E.js";
+
 // src/messages.ts
 import { z } from "zod/v4";
 var themeColorsSchema = z.object({
@@ -140,15 +148,22 @@ var LUMIO_EVENT_TYPES = [
   "youtube:gift_membership",
   "youtube:gift_membership_received",
   "youtube:poll",
-  // Kick
+  // YouTube stream lifecycle (ZAF-1444 / ZAF-622 §75) — emitted by the poll-driven
+  // YouTube worker on the channel-status online/offline edge, mirroring Twitch/Kick.
+  "youtube:stream_online",
+  "youtube:stream_offline",
+  // Kick — the webhook receiver normalizes every Kick payload into these types
+  // (ZAF-1624): canonical fields on top, the original payload kept in `raw`.
   "kick:follower",
   "kick:subscribe",
+  "kick:resub",
   "kick:gift",
+  "kick:kicks",
+  "kick:reward",
+  "kick:reward_status",
   "kick:stream_online",
   "kick:stream_offline",
-  // Trovo
-  "trovo:subscribe",
-  "trovo:spell",
+  "kick:stream_update",
   // Spotify
   "spotify:track",
   "spotify:play",
@@ -168,7 +183,6 @@ var LUMIO_EVENT_TYPES = [
   "twitch:chat",
   "youtube:chat",
   "kick:chat",
-  "trovo:chat",
   // Chat (cross-platform catch-all — fires for ALL platforms)
   "chat:message"
 ];
@@ -268,6 +282,7 @@ var HOST_METHODS = {
 };
 export {
   ACTION_TYPES,
+  EXTENSION_RUNTIME_LABEL_PLACEHOLDER,
   HOST_METHODS,
   LUMIO_COMPONENT_TYPES,
   LUMIO_EVENT_TYPES,
@@ -279,7 +294,11 @@ export {
   errorMessageSchema,
   eventMessageSchema,
   extensionConfigSchema,
+  extensionRuntimeLabel,
+  extensionRuntimeOrigin,
+  extensionRuntimeOriginLabel,
   initMessageSchema,
+  isValidExtensionRuntimeOriginTemplate,
   lumioActionTypeSchema,
   lumioEventTypeSchema,
   lumioMessageSchema,

package/dist/origin.d.ts

@@ -0,0 +1,24 @@
+/** Placeholder that a runtime origin template carries in place of the label. */
+declare const EXTENSION_RUNTIME_LABEL_PLACEHOLDER = "{label}";
+/**
+ * The runtime host label for an extension: its UUID as 32 lowercase hex
+ * characters. Returns `null` unless `extensionId` is a canonical lowercase,
+ * hyphenated UUID.
+ */
+declare function extensionRuntimeLabel(extensionId: string): string | null;
+/**
+ * The runtime origin for an extension under a template such as
+ * `https://{label}.lumio.ext.staging.zaflun.dev`. Returns `null` for an invalid
+ * extension id or an invalid template.
+ */
+declare function extensionRuntimeOrigin(extensionId: string, template: string): string | null;
+/**
+ * If `origin` is a runtime origin under `template`, returns its 32-hex label;
+ * otherwise `null`. Used where the extension id is not known, e.g. the runtime
+ * checking its own `location.origin`.
+ */
+declare function extensionRuntimeOriginLabel(origin: string, template: string): string | null;
+/** Whether `template` is a usable runtime origin template. */
+declare function isValidExtensionRuntimeOriginTemplate(template: string): boolean;
+
+export { EXTENSION_RUNTIME_LABEL_PLACEHOLDER, extensionRuntimeLabel, extensionRuntimeOrigin, extensionRuntimeOriginLabel, isValidExtensionRuntimeOriginTemplate };

package/dist/origin.js

@@ -0,0 +1,14 @@
+import {
+  EXTENSION_RUNTIME_LABEL_PLACEHOLDER,
+  extensionRuntimeLabel,
+  extensionRuntimeOrigin,
+  extensionRuntimeOriginLabel,
+  isValidExtensionRuntimeOriginTemplate
+} from "./chunk-746VSR4E.js";
+export {
+  EXTENSION_RUNTIME_LABEL_PLACEHOLDER,
+  extensionRuntimeLabel,
+  extensionRuntimeOrigin,
+  extensionRuntimeOriginLabel,
+  isValidExtensionRuntimeOriginTemplate
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaflun/lumio-protocol",
-  "version": "0.2.4",
+  "version": "0.6.0",
   "description": "Wire-format types for Lumio extension iframe-to-host communication",
   "type": "module",
   "main": "dist/index.js",
@@ -9,6 +9,10 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./origin": {
+      "import": "./dist/origin.js",
+      "types": "./dist/origin.d.ts"
     }
   },
   "publishConfig": {
@@ -42,7 +46,7 @@
     "email": "developers@zaflun.com"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
+    "build": "tsup src/index.ts src/origin.ts --format esm --dts --clean",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src/",
     "test": "vitest run"