@zaflun/lumio-protocol 0.2.4 → 0.9.0

package/CHANGELOG.md

@@ -5,6 +5,134 @@ 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.9.0
+
+### Added
+
+- **Typed event payloads** — `LUMIO_EVENT_PAYLOAD_SCHEMAS` holds one zod
+  schema per `LUMIO_EVENT_TYPES` entry for the `data` of an `event.platform`
+  notification (the backend's event `raw`; a `ChatMessageInput` for the chat
+  types). `LumioEventPayloadMap` / `LumioEventPayload<K>` are the inferred
+  types, `ChatMessagePayload` and `ModerationLogPayload` the shared ones.
+  `lumioEventPayloadSchema(type)` and `parseLumioEventPayload(type, data)`
+  validate a payload. The map is checked with `satisfies` against
+  `LumioEventType`, so a new event type without a schema fails typecheck. The
+  shapes follow the golden fixtures the backend exports to `fixtures/events/`.
+  Object schemas are loose: fields the backend adds later are kept, typed
+  `unknown`. The wire format is unchanged.
+
+### Changed
+
+- **`twitch:gift_sub` is now `twitch:gift`** in `LUMIO_EVENT_TYPES`. The
+  backend has always emitted gifted subs as `twitch:gift`, so no event ever
+  matched `twitch:gift_sub`. Replace the type in `useLumioEvent()` calls and
+  `event()` triggers. Breaking.
+
+## 0.8.0
+
+### Added
+
+- **`SERVER_FUNCTION_ERRORS`** — the JSON-RPC error codes a host answers a
+  failed `server.query` / `server.mutation` with (`INVALID_REQUEST`,
+  `UNAVAILABLE`, `DENIED`, `UNKNOWN_FUNCTION`, `INVALID_PARAMS`, `FAILED`),
+  and the `ServerFunctionErrorCode` type. `ServerQueryParams` /
+  `ServerMutationParams` document their results: `server.query` resolves with
+  the rows, `server.mutation` with the written row or `null`. Additive.
+- **`server.realtime`** — `HOST_METHODS.SERVER_REALTIME` (`"server.realtime"`)
+  is the host → worker notification that carries a message a handler of the
+  install pushed with `ctx.realtime.push(topic, payload)`, with
+  `ServerRealtimeParams` (`{ topic; payload }`). `REALTIME_LIMITS` holds the
+  push rules (`TOPIC_PATTERN`, `MAX_PAYLOAD_BYTES` 16 KiB,
+  `MAX_PUSHES_PER_INVOCATION` 32, `MAX_PUSHES_PER_MINUTE` 300 and
+  `MAX_BYTES_PER_MINUTE` 1 MiB per install). Additive.
+
+### Removed
+
+- **`interactive` target** — `LifecycleInitParams["target"]` and the
+  `extensionConfigSchema` `target` enum accept only `editor` and `layer`. No
+  host ever rendered an `interactive` surface; viewers interact through chat
+  commands and channel point rewards (`twitch:reward`, `kick:reward`) that a
+  bot-module handler turns into `ctx.realtime.push`, received with
+  `server.realtime`.
+
+  **Breaking for consumers** that pass or `switch` over `"interactive"`. Drop
+  that arm; an init message carrying `target: "interactive"` now fails
+  validation.
+
+## 0.7.0
+
+### Added
+
+- **`action.execute`** — `WORKER_METHODS.ACTION_EXECUTE` (`"action.execute"`)
+  is the worker → host request `useLumioAction()` sends, with
+  `ActionExecuteParams` (`{ action: LumioActionType; params }`) and
+  `ActionExecuteResult` (`{ data }`). `ACTION_EXECUTE_ERRORS` lists the
+  JSON-RPC error codes a host answers a failed action with (`INVALID_REQUEST`,
+  `UNAVAILABLE`, `DENIED`, `UNKNOWN_ACTION`, `INVALID_PARAMS`, `FAILED`).
+  Additive.
+- **Twitch reward lifecycle event types** — `twitch:reward_status`,
+  `twitch:reward_add`, `twitch:reward_update` and `twitch:reward_remove` are in
+  `LUMIO_EVENT_TYPES`, `LumioEventType` and the `lumioEventTypeSchema` Zod enum.
+  `twitch:reward_status` is a redemption's status change (`fulfilled` /
+  `canceled`) with the same shape as `twitch:reward`. `twitch:reward_add` /
+  `_update` / `_remove` fire when the streamer creates, changes or deletes a
+  channel-point reward on Twitch and carry the Twitch custom-reward object; they
+  are delivered live only (`broadcast_only`) and never appear in the event
+  history. Additive.
+
+## 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 +143,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
+};