Skip to main content

SDK Client Reference

Complete reference for @zaflun/lumio-sdk — the client-side library used in editor.tsx, layer.tsx, and interactive.tsx surfaces.

Import​

import { Lumio, Box, Text, useLumioEvent, useLumioConfig /* ... */ } from "@zaflun/lumio-sdk";

Hooks​

useLumioConfig​

Read and write the extension's configuration set by the editor panel.

function useLumioConfig<T = Record<string, unknown>>(): {
  config: T | null;
  setConfig: (patch: Partial<T>) => Promise<void>;
  loading: boolean;
};

setConfig performs a shallow merge — only provided keys are updated. Available in all surfaces.

useLumioEvent​

Subscribe to a live stream event. Returns the latest event of the given type, or null before the first event.

function useLumioEvent<T = unknown>(eventType: LumioEventType): LumioEvent<T> | null;

The hook reference changes every time a new event arrives. Use in a useEffect dependency array to respond to each event individually.

Supported event types: "twitch:follower", "twitch:subscriber", "twitch:cheer", "twitch:raid", "twitch:redemption", "youtube:subscriber", "youtube:member", "youtube:superchat", "spotify:track", "streamelements:tip", "chat:message".

useLumioAction​

Call a server function defined in server/functions.ts.

function useLumioAction(actionName: string): {
  invoke: (args: Record<string, unknown>) => Promise<unknown>;
  loading: boolean;
  error: Error | null;
};

invoke is stable across renders (memoized). loading is true while the server call is in flight.

useExtensionStorage​

Read and write per-install or global storage from the client side.

function useExtensionStorage<T>(
  scope: "global" | "install",
  ...keys: string[]
): {
  data: T | null;
  loading: boolean;
  set: (value: T) => Promise<void>;
  remove: () => Promise<void>;
  refetch: () => Promise<void>;
};

Client-side storage access requires "storage:read" (and "storage:write" to write) in permissions.

useLumioTheme​

Returns the streamer's active overlay theme.

function useLumioTheme(): LumioTheme;

interface LumioTheme {
  mode: "light" | "dark";
  primaryColor: string;        // hex color
  fontFamily: string;
  borderRadius: number;        // px
}

useLumioIdentity​

Returns the authenticated viewer's identity on the interactive page. Always null on layer and editor.

function useLumioIdentity(): LumioIdentity | null;

interface LumioIdentity {
  userId: string;
  userName: string;
  platform: "twitch" | "youtube" | "kick" | "trovo" | null;
  platformUserId: string | null;
  isAuthenticated: boolean;
}

useQuery​

Declarative query hook — calls a server query() function and returns the result.

function useQuery<T>(
  queryName: string,
  args: Record<string, unknown>,
  options?: { refetchInterval?: number }
): {
  data: T | null;
  loading: boolean;
  error: Error | null;
  refetch: () => Promise<void>;
};

refetchInterval polls on an interval (milliseconds). Use useLumioAction instead if you need imperative control.

useMutation​

Imperative mutation hook — wraps a server action() call with loading and error state.

function useMutation<TArgs, TResult>(
  actionName: string
): {
  mutate: (args: TArgs) => Promise<TResult>;
  loading: boolean;
  error: Error | null;
  reset: () => void;
};

Components​

Lumio.render​

Entry point for mounting a surface.

Lumio.render(element: React.ReactElement, options: { target: "layer" | "editor" | "interactive" }): void;

Must be called exactly once per surface file.

Box​

A general-purpose layout container. Renders a <div>.

interface BoxProps {
  style?: React.CSSProperties;
  children?: React.ReactNode;
  onClick?: () => void;
  ref?: React.Ref<HTMLDivElement>;
  [key: string]: unknown; // data-* attributes passed through
}

Text​

Renders inline text with semantic variants.

interface TextProps {
  content: string;
  variant?: "default" | "heading" | "muted" | "label" | "code";
  style?: React.CSSProperties;
}

Image​

Renders an image with automatic HTTPS enforcement and lazy loading.

interface ImageProps {
  src: string;
  alt: string;
  style?: React.CSSProperties;
  onError?: () => void;
}

Input​

A text input field for use in the editor panel.

interface InputProps {
  label?: string;
  value: string;
  onChange: (value: string) => void;
  placeholder?: string;
  type?: "text" | "email" | "url" | "password" | "number";
  disabled?: boolean;
}

Select​

A dropdown select field for use in the editor panel.

interface SelectProps {
  label?: string;
  value: string;
  options: Array<{ value: string; label: string }>;
  onChange: (value: string) => void;
  disabled?: boolean;
}

Toggle​

A boolean toggle switch for use in the editor panel.

interface ToggleProps {
  label: string;
  checked: boolean;
  onChange: (checked: boolean) => void;
  disabled?: boolean;
}

Button​

An interactive button for use in the editor panel or interactive page.

interface ButtonProps {
  label: string;
  onClick: () => void;
  variant?: "primary" | "secondary" | "danger";
  loading?: boolean;
  disabled?: boolean;
  style?: React.CSSProperties;
}

Animation utilities​

defineKeyframes​

Registers a CSS keyframe animation and returns a unique name safe for use in animation: CSS properties.

function defineKeyframes(frames: Record<string, React.CSSProperties>): string;
const slideIn = defineKeyframes({
  from: { opacity: 0, transform: "translateY(-20px)" },
  to: { opacity: 1, transform: "translateY(0)" },
});

// Use in a Box style:
style={{ animation: `${slideIn} 0.4s ease forwards` }}

localFont​

Loads a font file bundled with the extension and returns a CSS font-family value.

function localFont(options: { src: string; weight?: string; style?: string }): string;
const myFont = localFont({ src: "./assets/CustomFont.woff2", weight: "400 700" });

<Box style={{ fontFamily: myFont }}>...</Box>