lib-maestro-dmx 1.0.0

package/dist/osc.d.ts

@@ -0,0 +1,45 @@
+export interface OscFloatArgument {
+    type: "float";
+    value: number;
+}
+export type OscArgument = boolean | number | string | OscFloatArgument;
+export interface OscMessage {
+    address: string;
+    args: OscArgument[];
+}
+export interface OscResponse extends OscMessage {
+    remoteAddress: string;
+    remotePort: number;
+}
+export interface OscClientOptions {
+    host: string;
+    port: number;
+    localPort?: number;
+}
+export interface OscThrottleOptions {
+    intervalMs?: number;
+}
+export declare function oscFloat(value: number): OscFloatArgument;
+export declare function encodeOscMessage(message: OscMessage): Buffer;
+export declare function decodeOscMessage(buffer: Buffer): OscMessage;
+export declare class OscClient {
+    private static readonly DEFAULT_THROTTLE_MS;
+    private readonly host;
+    private readonly port;
+    private readonly localPort?;
+    private readonly throttledSendStates;
+    private socket;
+    constructor(options: OscClientOptions);
+    get connected(): boolean;
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    send(address: string, ...args: OscArgument[]): Promise<void>;
+    sendThrottled(address: string, argsOrOptions: OscArgument | OscThrottleOptions, ...remainingArgs: OscArgument[]): Promise<void>;
+    probe(address: string, args?: OscArgument[], timeoutMs?: number): Promise<OscResponse[]>;
+    private getSocket;
+    private getThrottledSendState;
+    private pruneThrottledSendState;
+    private clearThrottledSendStates;
+    private normalizeThrottledSendArguments;
+    private isOscThrottleOptions;
+}

package/dist/osc.js

@@ -0,0 +1,279 @@
+import dgram from "node:dgram";
+function padToFourBytes(length) {
+    const remainder = length % 4;
+    return remainder === 0 ? length : length + (4 - remainder);
+}
+function encodeOscString(value) {
+    const raw = Buffer.from(value, "utf8");
+    const size = padToFourBytes(raw.length + 1);
+    const result = Buffer.alloc(size);
+    raw.copy(result, 0);
+    return result;
+}
+function decodeOscString(buffer, offset) {
+    const end = buffer.indexOf(0, offset);
+    if (end === -1) {
+        throw new Error("Invalid OSC string: missing null terminator.");
+    }
+    const value = buffer.toString("utf8", offset, end);
+    return {
+        value,
+        nextOffset: padToFourBytes(end + 1)
+    };
+}
+function encodeOscArgument(argument) {
+    if (isOscFloatArgument(argument)) {
+        const payload = Buffer.alloc(4);
+        payload.writeFloatBE(argument.value, 0);
+        return { typeTag: "f", payload };
+    }
+    if (typeof argument === "string") {
+        return {
+            typeTag: "s",
+            payload: encodeOscString(argument)
+        };
+    }
+    if (typeof argument === "number") {
+        if (Number.isInteger(argument)) {
+            const payload = Buffer.alloc(4);
+            payload.writeInt32BE(argument, 0);
+            return { typeTag: "i", payload };
+        }
+        const payload = Buffer.alloc(4);
+        payload.writeFloatBE(argument, 0);
+        return { typeTag: "f", payload };
+    }
+    return {
+        typeTag: argument ? "T" : "F",
+        payload: Buffer.alloc(0)
+    };
+}
+function isOscFloatArgument(argument) {
+    return typeof argument === "object" && argument !== null && argument.type === "float";
+}
+export function oscFloat(value) {
+    return {
+        type: "float",
+        value
+    };
+}
+export function encodeOscMessage(message) {
+    const address = encodeOscString(message.address);
+    const encodedArguments = message.args.map(encodeOscArgument);
+    const typeTagString = `,${encodedArguments.map((argument) => argument.typeTag).join("")}`;
+    const typeTags = encodeOscString(typeTagString);
+    const payload = encodedArguments.map((argument) => argument.payload);
+    return Buffer.concat([address, typeTags, ...payload]);
+}
+export function decodeOscMessage(buffer) {
+    let offset = 0;
+    const address = decodeOscString(buffer, offset);
+    offset = address.nextOffset;
+    const typeTags = decodeOscString(buffer, offset);
+    offset = typeTags.nextOffset;
+    if (!typeTags.value.startsWith(",")) {
+        throw new Error("Invalid OSC type tag string.");
+    }
+    const args = [];
+    for (const typeTag of typeTags.value.slice(1)) {
+        switch (typeTag) {
+            case "i":
+                args.push(buffer.readInt32BE(offset));
+                offset += 4;
+                break;
+            case "f":
+                args.push(buffer.readFloatBE(offset));
+                offset += 4;
+                break;
+            case "s": {
+                const value = decodeOscString(buffer, offset);
+                args.push(value.value);
+                offset = value.nextOffset;
+                break;
+            }
+            case "T":
+                args.push(true);
+                break;
+            case "F":
+                args.push(false);
+                break;
+            default:
+                throw new Error(`Unsupported OSC type tag "${typeTag}".`);
+        }
+    }
+    return {
+        address: address.value,
+        args
+    };
+}
+export class OscClient {
+    static DEFAULT_THROTTLE_MS = 250;
+    host;
+    port;
+    localPort;
+    throttledSendStates = new Map();
+    socket;
+    constructor(options) {
+        this.host = options.host;
+        this.port = options.port;
+        this.localPort = options.localPort;
+    }
+    get connected() {
+        return this.socket !== undefined;
+    }
+    async connect() {
+        if (this.socket) {
+            return;
+        }
+        const socket = dgram.createSocket("udp4");
+        await new Promise((resolve, reject) => {
+            socket.once("error", reject);
+            socket.bind(this.localPort ?? 0, () => {
+                socket.off("error", reject);
+                resolve();
+            });
+        });
+        this.socket = socket;
+    }
+    async close() {
+        this.clearThrottledSendStates();
+        if (!this.socket) {
+            return;
+        }
+        const socket = this.socket;
+        this.socket = undefined;
+        await new Promise((resolve, reject) => {
+            const onClose = () => {
+                socket.off("error", onError);
+                resolve();
+            };
+            const onError = (error) => {
+                socket.off("close", onClose);
+                reject(error);
+            };
+            socket.once("close", onClose);
+            socket.once("error", onError);
+            socket.close();
+        });
+    }
+    async send(address, ...args) {
+        const socket = await this.getSocket();
+        const message = encodeOscMessage({ address, args });
+        await new Promise((resolve, reject) => {
+            socket.send(message, this.port, this.host, (error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            });
+        });
+    }
+    async sendThrottled(address, argsOrOptions, ...remainingArgs) {
+        const { args, intervalMs } = this.normalizeThrottledSendArguments(argsOrOptions, remainingArgs);
+        const state = this.getThrottledSendState(address);
+        const now = Date.now();
+        if (state.lastSentAt === undefined || now - state.lastSentAt >= intervalMs) {
+            state.lastSentAt = now;
+            void this.send(address, ...args).catch(() => { });
+            return;
+        }
+        state.pendingArgs = args;
+        if (state.timer) {
+            return;
+        }
+        const delayMs = Math.max(intervalMs - (now - state.lastSentAt), 0);
+        state.timer = setTimeout(() => {
+            state.timer = undefined;
+            const pendingArgs = state.pendingArgs;
+            state.pendingArgs = undefined;
+            if (!pendingArgs) {
+                this.pruneThrottledSendState(address, state);
+                return;
+            }
+            state.lastSentAt = Date.now();
+            void this.send(address, ...pendingArgs)
+                .catch(() => { })
+                .finally(() => {
+                this.pruneThrottledSendState(address, state);
+            });
+        }, delayMs);
+    }
+    async probe(address, args = [], timeoutMs = 1000) {
+        const socket = await this.getSocket();
+        const responses = [];
+        const onMessage = (buffer, remote) => {
+            try {
+                const message = decodeOscMessage(buffer);
+                responses.push({
+                    ...message,
+                    remoteAddress: remote.address,
+                    remotePort: remote.port
+                });
+            }
+            catch {
+                // Ignore packets that are not decodable as plain OSC messages.
+            }
+        };
+        socket.on("message", onMessage);
+        try {
+            await this.send(address, ...args);
+            await new Promise((resolve) => {
+                setTimeout(resolve, timeoutMs);
+            });
+        }
+        finally {
+            socket.off("message", onMessage);
+        }
+        return responses;
+    }
+    async getSocket() {
+        await this.connect();
+        if (!this.socket) {
+            throw new Error("OSC socket is not available.");
+        }
+        return this.socket;
+    }
+    getThrottledSendState(address) {
+        const existingState = this.throttledSendStates.get(address);
+        if (existingState) {
+            return existingState;
+        }
+        const newState = {
+            lastSentAt: undefined,
+            pendingArgs: undefined,
+            timer: undefined
+        };
+        this.throttledSendStates.set(address, newState);
+        return newState;
+    }
+    pruneThrottledSendState(address, state) {
+        if (state.timer || state.pendingArgs) {
+            return;
+        }
+        this.throttledSendStates.delete(address);
+    }
+    clearThrottledSendStates() {
+        for (const state of this.throttledSendStates.values()) {
+            if (state.timer) {
+                clearTimeout(state.timer);
+            }
+        }
+        this.throttledSendStates.clear();
+    }
+    normalizeThrottledSendArguments(argsOrOptions, remainingArgs) {
+        if (this.isOscThrottleOptions(argsOrOptions)) {
+            return {
+                args: remainingArgs,
+                intervalMs: argsOrOptions.intervalMs ?? OscClient.DEFAULT_THROTTLE_MS
+            };
+        }
+        return {
+            args: [argsOrOptions, ...remainingArgs],
+            intervalMs: OscClient.DEFAULT_THROTTLE_MS
+        };
+    }
+    isOscThrottleOptions(value) {
+        return typeof value === "object" && value !== null && "intervalMs" in value;
+    }
+}

package/dist/patterns.d.ts

@@ -0,0 +1,35 @@
+import { HttpClient } from "./http.js";
+import { ReadApi } from "./read-api.js";
+export interface PatternParameter {
+    param: string;
+    name?: string;
+    description?: string;
+    shape?: string[];
+}
+export interface PatternDefinition {
+    id: string;
+    name: string;
+    description?: string;
+    params: PatternParameter[];
+    advancedParams: PatternParameter[];
+}
+export interface PatternManifest {
+    interfaceVersion?: string;
+    id: string;
+    name: string;
+    description?: string;
+    patterns: PatternDefinition[];
+}
+export interface PatternsState {
+    manifests: PatternManifest[];
+    fetchedAt: Date;
+}
+interface PatternsApiResponse {
+    manifests?: unknown;
+}
+export declare class PatternsApi extends ReadApi<PatternsState, PatternsApiResponse> {
+    constructor(httpClient: HttpClient);
+    protected getPath(): string;
+    protected normalizeResponse(response: PatternsApiResponse, fetchedAt: Date): PatternsState;
+}
+export {};

package/dist/patterns.js

@@ -0,0 +1,69 @@
+import { HttpClient } from "./http.js";
+import { isRecord, normalizeArray, toOptionalString } from "./normalize.js";
+import { ReadApi } from "./read-api.js";
+function normalizePatternParameter(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const param = toOptionalString(value.param);
+    if (!param) {
+        return undefined;
+    }
+    const shape = Array.isArray(value.shape)
+        ? value.shape.filter((entry) => typeof entry === "string")
+        : undefined;
+    return {
+        param,
+        name: toOptionalString(value.name),
+        description: toOptionalString(value.description),
+        shape: shape?.length ? shape : undefined
+    };
+}
+function normalizePatternDefinition(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const id = toOptionalString(value.id);
+    const name = toOptionalString(value.name);
+    if (!id || !name) {
+        return undefined;
+    }
+    return {
+        id,
+        name,
+        description: toOptionalString(value.description),
+        params: normalizeArray(value.params, normalizePatternParameter),
+        advancedParams: normalizeArray(value.advancedParams, normalizePatternParameter)
+    };
+}
+function normalizePatternManifest(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const id = toOptionalString(value.id);
+    const name = toOptionalString(value.name);
+    if (!id || !name) {
+        return undefined;
+    }
+    return {
+        interfaceVersion: toOptionalString(value.interfaceVersion),
+        id,
+        name,
+        description: toOptionalString(value.description),
+        patterns: normalizeArray(value.patterns, normalizePatternDefinition)
+    };
+}
+export class PatternsApi extends ReadApi {
+    constructor(httpClient) {
+        super(httpClient);
+    }
+    getPath() {
+        return "/api/v1/patterns";
+    }
+    normalizeResponse(response, fetchedAt) {
+        return {
+            manifests: normalizeArray(response.manifests, normalizePatternManifest),
+            fetchedAt
+        };
+    }
+}

package/dist/read/brightness.d.ts

@@ -0,0 +1,17 @@
+import { HttpClient } from "../transport/http.js";
+import { ReadApi } from "./read-api.js";
+/** Snapshot of the global MaestroDMX stage brightness. */
+export interface BrightnessState {
+    value?: number;
+    fetchedAt: Date;
+}
+interface BrightnessApiResponse {
+    value?: unknown;
+}
+/** Reader for `/api/v1/brightness`. */
+export declare class BrightnessApi extends ReadApi<BrightnessState, BrightnessApiResponse> {
+    constructor(httpClient: HttpClient);
+    protected getPath(): string;
+    protected normalizeResponse(response: BrightnessApiResponse, fetchedAt: Date): BrightnessState;
+}
+export {};

package/dist/read/brightness.js

@@ -0,0 +1,18 @@
+import { toOptionalNumber } from "../internal/normalize.js";
+import { HttpClient } from "../transport/http.js";
+import { ReadApi } from "./read-api.js";
+/** Reader for `/api/v1/brightness`. */
+export class BrightnessApi extends ReadApi {
+    constructor(httpClient) {
+        super(httpClient);
+    }
+    getPath() {
+        return "/api/v1/brightness";
+    }
+    normalizeResponse(response, fetchedAt) {
+        return {
+            value: toOptionalNumber(response.value),
+            fetchedAt
+        };
+    }
+}

package/dist/read/color-palettes.d.ts

@@ -0,0 +1,46 @@
+import { HttpClient } from "../transport/http.js";
+import { ReadApi } from "./read-api.js";
+/** One RGBWAUV-style color stop in an extended MaestroDMX palette. */
+export interface PaletteColor {
+    r?: number;
+    g?: number;
+    b?: number;
+    w?: number;
+    am?: number;
+    u?: number;
+}
+/** One color palette definition returned by MaestroDMX. */
+export interface ColorPalette {
+    paletteId: string;
+    name: string;
+    type?: string;
+    children: string[];
+    hexColors: string[];
+    colors: PaletteColor[];
+    readOnly?: boolean;
+}
+/** Snapshot of the MaestroDMX color palette catalog. */
+export interface ColorPalettesState {
+    palettes: ColorPalette[];
+    fetchedAt: Date;
+}
+interface ColorPalettesApiResponse {
+    palettes?: unknown;
+}
+/** Reader for `/api/v1/palettes/color`. */
+export declare class ColorPalettesApi extends ReadApi<ColorPalettesState, ColorPalettesApiResponse> {
+    constructor(httpClient: HttpClient);
+    protected getPath(): string;
+    protected normalizeResponse(response: ColorPalettesApiResponse, fetchedAt: Date): ColorPalettesState;
+    /** Finds one palette by palette id. */
+    findById(paletteId: string, snapshot?: ColorPalettesState): ColorPalette | undefined;
+    /** Finds one palette by its display name. */
+    findByName(name: string, snapshot?: ColorPalettesState): ColorPalette | undefined;
+    /** Returns grouped palettes only. */
+    listGroups(snapshot?: ColorPalettesState): ColorPalette[];
+    /** Returns individual palettes only. */
+    listLeafPalettes(snapshot?: ColorPalettesState): ColorPalette[];
+    /** Resolves the child palettes referenced by a grouped palette. */
+    resolveChildren(paletteId: string, snapshot?: ColorPalettesState): ColorPalette[];
+}
+export {};

package/dist/read/color-palettes.js

@@ -0,0 +1,86 @@
+import { isRecord, normalizeArray, toOptionalBoolean, toOptionalNumber, toOptionalString } from "../internal/normalize.js";
+import { HttpClient } from "../transport/http.js";
+import { ReadApi } from "./read-api.js";
+function normalizePaletteColor(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    return {
+        r: toOptionalNumber(value.r),
+        g: toOptionalNumber(value.g),
+        b: toOptionalNumber(value.b),
+        w: toOptionalNumber(value.w),
+        am: toOptionalNumber(value.am),
+        u: toOptionalNumber(value.u)
+    };
+}
+function normalizeColorPalette(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const paletteId = toOptionalString(value.paletteId);
+    const name = toOptionalString(value.name);
+    if (!paletteId || !name) {
+        return undefined;
+    }
+    const hexColors = Array.isArray(value.hexColors)
+        ? value.hexColors
+            .filter((entry) => typeof entry === "string" || typeof entry === "number")
+            .map((entry) => String(entry))
+        : [];
+    const children = Array.isArray(value.children)
+        ? value.children
+            .filter((entry) => typeof entry === "string" || typeof entry === "number")
+            .map((entry) => String(entry))
+        : [];
+    return {
+        paletteId,
+        name,
+        type: toOptionalString(value.type),
+        children,
+        hexColors,
+        colors: normalizeArray(value.colors, normalizePaletteColor),
+        readOnly: toOptionalBoolean(value.readOnly)
+    };
+}
+/** Reader for `/api/v1/palettes/color`. */
+export class ColorPalettesApi extends ReadApi {
+    constructor(httpClient) {
+        super(httpClient);
+    }
+    getPath() {
+        return "/api/v1/palettes/color";
+    }
+    normalizeResponse(response, fetchedAt) {
+        return {
+            palettes: normalizeArray(response.palettes, normalizeColorPalette),
+            fetchedAt
+        };
+    }
+    /** Finds one palette by palette id. */
+    findById(paletteId, snapshot) {
+        return this.resolveSnapshot(snapshot)?.palettes.find((palette) => palette.paletteId === paletteId);
+    }
+    /** Finds one palette by its display name. */
+    findByName(name, snapshot) {
+        return this.resolveSnapshot(snapshot)?.palettes.find((palette) => palette.name === name);
+    }
+    /** Returns grouped palettes only. */
+    listGroups(snapshot) {
+        return this.resolveSnapshot(snapshot)?.palettes.filter((palette) => palette.type === "GROUP") ?? [];
+    }
+    /** Returns individual palettes only. */
+    listLeafPalettes(snapshot) {
+        return this.resolveSnapshot(snapshot)?.palettes.filter((palette) => palette.type !== "GROUP") ?? [];
+    }
+    /** Resolves the child palettes referenced by a grouped palette. */
+    resolveChildren(paletteId, snapshot) {
+        const palette = this.findById(paletteId, snapshot);
+        if (!palette || palette.type !== "GROUP") {
+            return [];
+        }
+        return palette.children
+            .map((childId) => this.findById(childId, snapshot))
+            .filter((child) => child !== undefined);
+    }
+}

package/dist/read/fixture-groups.d.ts

@@ -0,0 +1,31 @@
+import { HttpClient } from "../transport/http.js";
+import { ReadApi } from "./read-api.js";
+/** Runtime fixture-group metadata for one MaestroDMX group. */
+export interface FixtureGroup {
+    id: string;
+    name?: string;
+    paramGroup?: string;
+    fixtureIds: string[];
+    mappingConfig: Record<string, unknown>;
+}
+/** Snapshot of the stage fixture-group topology used during runtime. */
+export interface FixtureGroupsState {
+    groups: FixtureGroup[];
+    fetchedAt: Date;
+}
+interface FixtureGroupsApiResponse {
+    fixtureGroup?: unknown;
+}
+/** Reader for `/api/v1/fixture_groups`. */
+export declare class FixtureGroupsApi extends ReadApi<FixtureGroupsState, FixtureGroupsApiResponse> {
+    constructor(httpClient: HttpClient);
+    protected getPath(): string;
+    protected normalizeResponse(response: FixtureGroupsApiResponse, fetchedAt: Date): FixtureGroupsState;
+    /** Finds a fixture group by internal group id. */
+    getGroupById(id: string, snapshot?: FixtureGroupsState): FixtureGroup | undefined;
+    /** Finds a fixture group by MaestroDMX param-group name or numeric index. */
+    getGroupByParamGroup(paramGroup: string | number, snapshot?: FixtureGroupsState): FixtureGroup | undefined;
+    /** Returns all fixture ids associated with one fixture group. */
+    listFixtureIds(group: string | number, snapshot?: FixtureGroupsState): string[];
+}
+export {};

package/dist/read/fixture-groups.js

@@ -0,0 +1,56 @@
+import { isRecord, normalizeArray, toOptionalString } from "../internal/normalize.js";
+import { HttpClient } from "../transport/http.js";
+import { ReadApi } from "./read-api.js";
+import { normalizeParamGroup } from "./shared.js";
+function normalizeFixtureGroup(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const id = toOptionalString(value.id);
+    if (!id) {
+        return undefined;
+    }
+    return {
+        id,
+        name: toOptionalString(value.name),
+        paramGroup: toOptionalString(value.paramGroup),
+        fixtureIds: Array.isArray(value.fixtureId)
+            ? value.fixtureId.filter((entry) => typeof entry === "string")
+            : [],
+        mappingConfig: isRecord(value.mappingConfig) ? value.mappingConfig : {}
+    };
+}
+/** Reader for `/api/v1/fixture_groups`. */
+export class FixtureGroupsApi extends ReadApi {
+    constructor(httpClient) {
+        super(httpClient);
+    }
+    getPath() {
+        return "/api/v1/fixture_groups";
+    }
+    normalizeResponse(response, fetchedAt) {
+        return {
+            groups: normalizeArray(response.fixtureGroup, normalizeFixtureGroup),
+            fetchedAt
+        };
+    }
+    /** Finds a fixture group by internal group id. */
+    getGroupById(id, snapshot) {
+        return this.resolveSnapshot(snapshot)?.groups.find((group) => group.id === id);
+    }
+    /** Finds a fixture group by MaestroDMX param-group name or numeric index. */
+    getGroupByParamGroup(paramGroup, snapshot) {
+        const resolvedSnapshot = this.resolveSnapshot(snapshot);
+        const normalizedParamGroup = normalizeParamGroup(paramGroup);
+        if (!resolvedSnapshot || !normalizedParamGroup) {
+            return undefined;
+        }
+        return resolvedSnapshot.groups.find((group) => group.paramGroup === normalizedParamGroup);
+    }
+    /** Returns all fixture ids associated with one fixture group. */
+    listFixtureIds(group, snapshot) {
+        return this.getGroupByParamGroup(group, snapshot)?.fixtureIds
+            ?? this.getGroupById(typeof group === "string" ? group : "", snapshot)?.fixtureIds
+            ?? [];
+    }
+}