openvibe-sdk/elements

type ElementSharing

export type ElementSharing = 'private' | 'link' | 'gallery';

type ElementRole

export type ElementRole = 'everyone' | 'follower' | 'subscriber' | 'vip' | 'operator' | 'owner';

type ElementShape

export type ElementShape = 'round' | 'pill' | 'square';

type ActionKind

export type ActionKind =
    | 'robot.drive_pulse' | 'robot.head_preset' | 'robot.headlight' | 'robot.say' | 'robot.macro'
    | 'chat.message' | 'chat.pin' | 'chat.poll'
    | 'screen.alert' | 'screen.animation' | 'screen.confetti' | 'screen.sound' | 'screen.tts'
    | 'screen.counter' | 'screen.state' | 'screen.visibility' | 'screen.scene'
    | 'stream.clip' | 'stream.moment' | 'stream.title' | 'stream.category'
    | 'ai.ask' | 'actor.task' | 'webhook.call' | 'money.tip_goal';

type ProductId

export type ProductId = 'bot' | 'chat' | 'live' | 'ai' | 'actor' | 'billing';

type TriggerKind

export type TriggerKind =
    | 'press' | 'hold' | 'double_press' | 'key' | 'gamepad' | 'chat_command' | 'chat_text'
    | 'follow' | 'tip' | 'ai_moment' | 'rundown_topic' | 'timer' | 'schedule'
    | 'robot_telemetry' | 'robot_event' | 'stream_start' | 'stream_end' | 'viewer_count' | 'element_event';

type ElementValue

export type ElementValue = boolean | number | string | Array<number | string>;

type ElementValues

export type ElementValues = Record<string, ElementValue>;

interface ElementsError

export interface ElementsError {
    /** Where the problem is, e.g. "/recipe/actions/0/product". */
    path: string;
    /** A plain sentence an editor can show after "Can't do that: ". */
    message: string;
}

interface ElementValidation

export interface ElementValidation {
    valid: boolean;
    errors: ElementsError[];
}

interface UiTrigger

One trigger declaration, or the fired occurrence shaped like it.

export interface UiTrigger {
    kind: TriggerKind;
    [key: string]: unknown;
}

interface UiAction

One action from the catalog, with the product that authorises it.

export interface UiAction {
    kind: ActionKind;
    product: ProductId;
    [key: string]: unknown;
}

interface ElementConditions

export interface ElementConditions {
    role?: ElementRole;
    /** Channel points only; stage 1 never charges money or Vibes. */
    cost?: { points: number };
    cooldown?: { per_person_seconds?: number; overall_seconds?: number };
    daily_cap?: { per_person?: number; overall?: number };
    live_only?: boolean;
    robot_turn_only?: boolean;
    chance?: { one_in: number };
}

interface ElementLook

export interface ElementLook {
    component: string;
    label: string;
    icon?: string;
    props?: Record<string, boolean | number | string>;
    style?: {
        tint?: string;
        shape?: ElementShape;
        opacity?: number;
        show_label?: boolean;
    };
}

interface ElementRecipe

export interface ElementRecipe {
    triggers: UiTrigger[];
    conditions?: ElementConditions;
    actions: UiAction[];
}

interface ElementModReference

export interface ElementModReference {
    id: string;
    version: string;
    sha256: string;
    capabilities?: ActionKind[];
}

interface UiElement

export interface UiElement {
    id?: string;
    revision?: number;
    name: string;
    description?: string;
    author: { name: string; subject?: SubjectRef };
    sharing: ElementSharing;
    look: ElementLook;
    recipe: ElementRecipe;
    capabilities: ActionKind[];
    initial_state?: ElementValues;
    mod?: ElementModReference;
    created_at?: string;
    updated_at?: string;
}

interface ElementState

export interface ElementState {
    values?: ElementValues;
    revision?: number;
}

interface ElementLimits

export interface ElementLimits {
    /** Milliseconds until this scope is ready; 0 when it is ready now. */
    cooldown(query: { scope: 'person' | 'overall'; elementId: string; actorId: string; at: number }): number | Promise<number>;
    /** How many times this scope already fired in the UTC day. */
    dailyCount(query: { scope: 'person' | 'overall'; elementId: string; actorId: string; day: string }): number | Promise<number>;
    /** Record an accepted fire so the cooldown and daily counters move. */
    hit(query: { elementId: string; actorId: string; at: number; day: string }): void | Promise<void>;
}

interface ElementSpend

export interface ElementSpend {
    points: number;
    elementId: string;
    actorId: string;
    subject: SubjectRef | null;
    at: number;
}

interface ElementSpendResult

export interface ElementSpendResult {
    ok: boolean;
    reason?: string;
    message?: string;
}

interface ElementSendInfo

export interface ElementSendInfo {
    element: { id?: string; name?: string; capabilities: ActionKind[] };
    actor: { subject?: SubjectRef; role?: ElementRole; name?: string };
    trigger: UiTrigger;
    /** The product that authorises this action; the host dispatches on it. */
    product: ProductId;
}

interface ElementSendResult

export interface ElementSendResult {
    ok: boolean;
    result?: unknown;
    reason?: string;
    message?: string;
}

interface ElementsHostContext

The host's side of run(). It is supplied by the product that owns the press.

export interface ElementsHostContext {
    now?: number;
    random?: () => number;
    isLive?: boolean;
    robotInTurn?: boolean;
    element: { id?: string; name?: string; capabilities: ActionKind[] };
    actor?: { subject?: SubjectRef; role?: ElementRole; name?: string };
    limits?: ElementLimits;
    spend?: (query: ElementSpend) => ElementSpendResult | Promise<ElementSpendResult>;
    refund?: (query: ElementSpend) => void | Promise<void>;
    send: (action: UiAction, info: ElementSendInfo) => ElementSendResult | Promise<ElementSendResult>;
}

type ElementsRefusalCode

export type ElementsRefusalCode =
    | 'invalid' | 'trigger' | 'capability' | 'role' | 'not_live' | 'robot_turn' | 'chance'
    | 'cooldown' | 'daily_cap' | 'points' | 'limits' | 'action';

interface ElementsRunSuccess

export interface ElementsRunSuccess {
    ok: true;
    pointsSpent: number;
    actions: Array<{ action: UiAction; result: unknown }>;
}

interface ElementsRunRefusal

export interface ElementsRunRefusal {
    ok: false;
    code: ElementsRefusalCode;
    message: string;
    retryAfterMs?: number;
    scope?: 'person' | 'overall';
    refusedAction?: ActionKind;
    refunded?: boolean;
    pointsSpent?: number;
    actions?: Array<{ action: UiAction; result: unknown }>;
}

type ElementsRunResult

export type ElementsRunResult = ElementsRunSuccess | ElementsRunRefusal;

interface ElementsReduceResult

export interface ElementsReduceResult {
    values: ElementValues;
    revision: number;
    changed: boolean;
    errors: ElementsError[];
}

function validate

export declare function validate(element: unknown): ElementValidation;

function run

export declare function run(recipe: ElementRecipe, trigger: UiTrigger, ctx: ElementsHostContext): Promise<ElementsRunResult>;

function reduce

export declare function reduce(state: ElementState | null, actions: UiAction[], options?: { maxKeys?: number }): ElementsReduceResult;

function isValidValue

export declare function isValidValue(value: unknown): boolean;

const PRODUCTS

export declare const PRODUCTS: Record<ActionKind, ProductId>;

const ACTION_KINDS

export declare const ACTION_KINDS: ActionKind[];

const ACTION_SET

export declare const ACTION_SET: Set<ActionKind>;

const TRIGGER_KINDS

export declare const TRIGGER_KINDS: TriggerKind[];

const TRIGGER_SET

export declare const TRIGGER_SET: Set<TriggerKind>;

const ROBOT_ACTIONS

export declare const ROBOT_ACTIONS: ActionKind[];

const ROLES

export declare const ROLES: ElementRole[];

const ROLE_RANK

export declare const ROLE_RANK: Record<ElementRole, number>;