@laplace.live/persona-sdk 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 LAPLACE Live!
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# @laplace.live/persona-sdk
+
+TypeScript SDK and wire schema for the [LAPLACE Persona](https://github.com/laplace-live/persona)
+plugin API — a token-authenticated WebSocket API for driving the avatar, scenes, expressions,
+motions, hotkeys, and tracking parameters from outside the app.
+
+Isomorphic: runs in Node ≥22, Bun, browsers, and OBS browser sources on the global `WebSocket`.
+One runtime dependency ([`zod`](https://zod.dev), backing the wire schemas).
+
+## Setup
+
+Enable the API in Persona under **Advanced → Plugin API**, create a key, and copy the token.
+
+```ts
+import { PersonaClient } from '@laplace.live/persona-sdk'
+
+const persona = new PersonaClient({ token: 'sk-lp-v1-…' })
+await persona.connect()
+
+// Typed request/response
+const { scenes, activeSceneId } = await persona.call('scene.list')
+await persona.call('expression.toggle', { name: 'Smile' })
+await persona.call('scene.patch', { behavior: { lookAtCursor: true } })
+
+// Events (subscriptions survive reconnects)
+persona.on('motion.started', m => console.log('playing', m.group))
+
+// Parameter leases: the value keeps applying until released; the SDK owns the
+// heartbeat, and if your process dies the parameter reverts within ~1 s.
+const mouth = persona.driveParameter('MouthOpen', 0.8)
+mouth.set(0.3)
+mouth.release()
+```
+
+By default the token travels as `?token=` (works in browsers). From Node you can use an
+`Authorization: Bearer` header instead by supplying a socket that can set headers, e.g. the
+[`ws`](https://www.npmjs.com/package/ws) package (install it separately — it is not a
+dependency of this SDK):
+
+```ts
+import WebSocket from 'ws'
+
+const persona = new PersonaClient({
+  token,
+  auth: 'header',
+  createWebSocket: (url, headers) => new WebSocket(url, { headers }) as unknown as globalThis.WebSocket,
+})
+```
+
+Treat the token like a password: it grants control of the app, including loading registered
+models and web overlays. The server listens on loopback unless LAN access is enabled in
+Persona's settings.

package/dist/client.d.ts

@@ -0,0 +1,95 @@
+import type { EventData, EventName } from './events.ts';
+import type { MethodName, MethodRequest, MethodResponse } from './methods.ts';
+import type { InjectTarget } from './types.ts';
+export type PersonaClientState = 'closed' | 'connecting' | 'open' | 'reconnecting';
+export interface PersonaClientOptions {
+    /** An API key created in Persona's settings. */
+    token: string;
+    /** Default `ws://127.0.0.1:25034`. */
+    url?: string;
+    /**
+     * How the token travels: `query` (`?token=`, works everywhere including browsers)
+     * or `header` (`Authorization: Bearer`, needs a WebSocket impl that accepts
+     * headers — pass one via `createWebSocket`).
+     */
+    auth?: 'query' | 'header';
+    /** Reconnect automatically after an unexpected close. Default true. */
+    reconnect?: boolean;
+    reconnectDelayMs?: number;
+    reconnectDelayMaxMs?: number;
+    requestTimeoutMs?: number;
+    /** Custom socket factory — for `ws` with headers, or tests. `headers` is set only for `auth: 'header'`. */
+    createWebSocket?: (url: string, headers: Record<string, string> | undefined) => WebSocket;
+    onStateChange?: (state: PersonaClientState) => void;
+    /** Non-fatal notices (protocol version mismatch). Default `console.warn`. */
+    onWarning?: (message: string) => void;
+}
+/** One held parameter lease. Values keep applying until `release()` (or the socket dies). */
+export interface InjectionHandle {
+    set(value: number): void;
+    release(): void;
+}
+/**
+ * Typed client for the Persona plugin API: correlated request/response, event
+ * subscriptions that survive reconnects, and parameter leases with an owned
+ * heartbeat so an injected value never silently expires while held.
+ */
+export declare class PersonaClient {
+    private readonly opts;
+    private ws;
+    private state;
+    private readonly pending;
+    private readonly listeners;
+    private readonly leases;
+    private heartbeat;
+    private reconnectTimer;
+    private reconnectAttempt;
+    private closedByUser;
+    private flushQueued;
+    private nextId;
+    private readonly idPrefix;
+    /** The server's `hello`, once connected. */
+    serverInfo: {
+        protocol: number;
+        app: {
+            name: string;
+            version: string;
+            platform: string;
+        };
+    } | null;
+    constructor(options: PersonaClientOptions);
+    getState(): PersonaClientState;
+    /** Open the connection and wait for the server's `hello`. Rejects on first failure. */
+    connect(): Promise<void>;
+    /** Close for good: pending calls reject, leases drop server-side via the lease timeout. */
+    close(): void;
+    /** Send one request and await its typed response. */
+    call<M extends MethodName>(method: M, ...args: MethodRequest<M> extends Record<never, never> ? [request?: MethodRequest<M>] : [request: MethodRequest<M>]): Promise<MethodResponse<M>>;
+    /**
+     * Listen for a server event. The subscription is established on the server and
+     * re-established after reconnects. @returns Unsubscribe.
+     */
+    on<E extends EventName>(event: E, cb: (data: EventData<E>) => void): () => void;
+    /**
+     * Hold a parameter lease: the value keeps applying (heartbeat every
+     * {@link INJECT_HEARTBEAT_MS} ms) until `release()`. A string target is
+     * shorthand for `{ type: 'input', id }`.
+     */
+    driveParameter(target: string | InjectTarget, value: number, opts?: {
+        weight?: number;
+        onError?: (e: Error) => void;
+    }): InjectionHandle;
+    private setState;
+    private warn;
+    private buildUrl;
+    private open;
+    private onHello;
+    private onServerMessage;
+    private failPending;
+    private scheduleReconnect;
+    private startHeartbeat;
+    private stopHeartbeat;
+    /** Coalesce same-tick `set()` calls into one frame. */
+    private queueFlush;
+    private flushLeases;
+}

package/dist/client.js

@@ -0,0 +1,312 @@
+import { parseServerMessage } from "./envelope.js";
+import { PersonaApiError } from "./errors.js";
+import { DEFAULT_API_PORT, INJECT_HEARTBEAT_MS, injectTargetKey, PROTOCOL_VERSION } from "./protocol.js";
+const DEFAULTS = {
+    url: `ws://127.0.0.1:${String(DEFAULT_API_PORT)}`,
+    reconnectDelayMs: 500,
+    reconnectDelayMaxMs: 10_000,
+    requestTimeoutMs: 10_000,
+};
+/**
+ * Typed client for the Persona plugin API: correlated request/response, event
+ * subscriptions that survive reconnects, and parameter leases with an owned
+ * heartbeat so an injected value never silently expires while held.
+ */
+export class PersonaClient {
+    opts;
+    ws = null;
+    state = 'closed';
+    pending = new Map();
+    listeners = new Map();
+    leases = new Map();
+    heartbeat = null;
+    reconnectTimer = null;
+    reconnectAttempt = 0;
+    closedByUser = false;
+    flushQueued = false;
+    nextId = 1;
+    idPrefix = Math.random().toString(36).slice(2, 10);
+    /** The server's `hello`, once connected. */
+    serverInfo = null;
+    constructor(options) {
+        this.opts = {
+            url: DEFAULTS.url,
+            auth: 'query',
+            reconnect: true,
+            ...options,
+        };
+    }
+    getState() {
+        return this.state;
+    }
+    /** Open the connection and wait for the server's `hello`. Rejects on first failure. */
+    async connect() {
+        if (this.state === 'open' || this.state === 'connecting')
+            return;
+        this.closedByUser = false;
+        this.setState('connecting');
+        await this.open();
+    }
+    /** Close for good: pending calls reject, leases drop server-side via the lease timeout. */
+    close() {
+        this.closedByUser = true;
+        if (this.reconnectTimer !== null)
+            clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = null;
+        this.stopHeartbeat();
+        this.failPending(new Error('client closed'));
+        const ws = this.ws;
+        this.ws = null;
+        ws?.close();
+        this.setState('closed');
+    }
+    /** Send one request and await its typed response. */
+    call(method, ...args) {
+        const params = args[0];
+        const ws = this.ws;
+        if (ws === null || ws.readyState !== 1 /* OPEN */) {
+            return Promise.reject(new Error('not connected'));
+        }
+        const id = `${this.idPrefix}-${String(this.nextId++)}`;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`request timed out: ${method}`));
+            }, this.opts.requestTimeoutMs ?? DEFAULTS.requestTimeoutMs);
+            this.pending.set(id, { resolve: resolve, reject, timer });
+            ws.send(JSON.stringify({ kind: 'request', id, method, ...(params === undefined ? {} : { params }) }));
+        });
+    }
+    /**
+     * Listen for a server event. The subscription is established on the server and
+     * re-established after reconnects. @returns Unsubscribe.
+     */
+    on(event, cb) {
+        let set = this.listeners.get(event);
+        const isNew = set === undefined;
+        if (set === undefined) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        set.add(cb);
+        if (isNew && this.state === 'open') {
+            void this.call('events.subscribe', { events: [event] }).catch(() => undefined);
+        }
+        return () => {
+            const s = this.listeners.get(event);
+            if (!s)
+                return;
+            s.delete(cb);
+            if (s.size === 0) {
+                this.listeners.delete(event);
+                if (this.state === 'open')
+                    void this.call('events.unsubscribe', { events: [event] }).catch(() => undefined);
+            }
+        };
+    }
+    /**
+     * Hold a parameter lease: the value keeps applying (heartbeat every
+     * {@link INJECT_HEARTBEAT_MS} ms) until `release()`. A string target is
+     * shorthand for `{ type: 'input', id }`.
+     */
+    driveParameter(target, value, opts) {
+        const t = typeof target === 'string' ? { type: 'input', id: target } : target;
+        const key = injectTargetKey(t);
+        const lease = {
+            entry: { ...t, value, ...(opts?.weight === undefined ? {} : { weight: opts.weight }) },
+            ...(opts?.onError === undefined ? {} : { onError: opts.onError }),
+        };
+        this.leases.set(key, lease);
+        this.startHeartbeat();
+        this.queueFlush();
+        return {
+            set: (v) => {
+                const held = this.leases.get(key);
+                if (held !== lease)
+                    return; // released, or replaced by a newer handle
+                lease.entry.value = v;
+                this.queueFlush();
+            },
+            release: () => {
+                if (this.leases.get(key) !== lease)
+                    return;
+                this.leases.delete(key);
+                if (this.leases.size === 0)
+                    this.stopHeartbeat();
+                if (this.state === 'open') {
+                    const target = { type: t.type, id: t.id, ...(t.instanceId ? { instanceId: t.instanceId } : {}) };
+                    void this.call('param.release', { targets: [target] }).catch(() => undefined);
+                }
+            },
+        };
+    }
+    // ---- internals ----------------------------------------------------------------
+    setState(state) {
+        if (this.state === state)
+            return;
+        this.state = state;
+        this.opts.onStateChange?.(state);
+    }
+    warn(message) {
+        if (this.opts.onWarning)
+            this.opts.onWarning(message);
+        else
+            console.warn(`[persona-sdk] ${message}`);
+    }
+    buildUrl() {
+        if (this.opts.auth === 'header') {
+            return { url: this.opts.url, headers: { Authorization: `Bearer ${this.opts.token}` } };
+        }
+        const u = new URL(this.opts.url);
+        u.searchParams.set('token', this.opts.token);
+        return { url: u.toString(), headers: undefined };
+    }
+    open() {
+        const { url, headers } = this.buildUrl();
+        const ws = this.opts.createWebSocket
+            ? this.opts.createWebSocket(url, headers)
+            : headers === undefined
+                ? new WebSocket(url)
+                : (() => {
+                    throw new Error("auth: 'header' needs a createWebSocket factory that can set headers");
+                })();
+        this.ws = ws;
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const settle = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            };
+            ws.addEventListener('message', ev => {
+                const data = ev.data;
+                if (typeof data !== 'string')
+                    return;
+                const msg = parseServerMessage(data);
+                if (msg === null)
+                    return;
+                if (msg.kind === 'hello') {
+                    this.onHello(msg.protocol, msg.app);
+                    settle(null);
+                    return;
+                }
+                this.onServerMessage(msg);
+            });
+            ws.addEventListener('close', () => {
+                if (this.ws !== ws)
+                    return; // an intentional close already moved on
+                this.ws = null;
+                this.serverInfo = null;
+                this.failPending(new Error('connection closed'));
+                settle(new Error('connection closed'));
+                if (this.closedByUser) {
+                    this.setState('closed');
+                    return;
+                }
+                if (!this.opts.reconnect || this.state === 'connecting') {
+                    // Initial connect failed: report to the caller instead of retrying forever.
+                    this.setState('closed');
+                    return;
+                }
+                this.scheduleReconnect();
+            });
+            ws.addEventListener('error', () => {
+                // The close event follows and carries the terminal handling.
+            });
+        });
+    }
+    onHello(protocol, app) {
+        this.serverInfo = { protocol, app };
+        if (protocol !== PROTOCOL_VERSION) {
+            this.warn(`protocol version mismatch: server speaks v${String(protocol)}, SDK speaks v${String(PROTOCOL_VERSION)}`);
+        }
+        this.reconnectAttempt = 0;
+        this.setState('open');
+        const events = [...this.listeners.keys()];
+        if (events.length > 0)
+            void this.call('events.subscribe', { events }).catch(() => undefined);
+        if (this.leases.size > 0)
+            this.queueFlush();
+    }
+    onServerMessage(msg) {
+        if (msg.kind === 'event') {
+            const set = this.listeners.get(msg.event);
+            if (!set)
+                return;
+            for (const cb of set)
+                cb(msg.data);
+            return;
+        }
+        const { id } = msg;
+        if (id === null)
+            return;
+        const p = this.pending.get(id);
+        if (!p)
+            return;
+        this.pending.delete(id);
+        clearTimeout(p.timer);
+        if (msg.kind === 'response')
+            p.resolve(msg.result);
+        else
+            p.reject(new PersonaApiError(msg.code, msg.message));
+    }
+    failPending(err) {
+        for (const p of this.pending.values()) {
+            clearTimeout(p.timer);
+            p.reject(err);
+        }
+        this.pending.clear();
+    }
+    scheduleReconnect() {
+        this.setState('reconnecting');
+        const base = this.opts.reconnectDelayMs ?? DEFAULTS.reconnectDelayMs;
+        const max = this.opts.reconnectDelayMaxMs ?? DEFAULTS.reconnectDelayMaxMs;
+        const delay = Math.min(base * 2 ** this.reconnectAttempt, max);
+        this.reconnectAttempt++;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            if (this.closedByUser)
+                return;
+            void this.open().catch(() => undefined); // close handler schedules the next attempt
+        }, delay);
+    }
+    // ---- lease heartbeat ----------------------------------------------------------
+    startHeartbeat() {
+        if (this.heartbeat !== null)
+            return;
+        this.heartbeat = setInterval(() => {
+            this.flushLeases();
+        }, INJECT_HEARTBEAT_MS);
+    }
+    stopHeartbeat() {
+        if (this.heartbeat === null)
+            return;
+        clearInterval(this.heartbeat);
+        this.heartbeat = null;
+    }
+    /** Coalesce same-tick `set()` calls into one frame. */
+    queueFlush() {
+        if (this.flushQueued)
+            return;
+        this.flushQueued = true;
+        queueMicrotask(() => {
+            this.flushQueued = false;
+            this.flushLeases();
+        });
+    }
+    flushLeases() {
+        if (this.leases.size === 0 || this.state !== 'open')
+            return;
+        const entries = [...this.leases.values()].map(l => l.entry);
+        const errorSinks = [...this.leases.values()];
+        void this.call('param.inject', { entries }).catch((e) => {
+            const err = e instanceof Error ? e : new Error(String(e));
+            for (const l of errorSinks)
+                l.onError?.(err);
+        });
+    }
+}

package/dist/envelope.d.ts

@@ -0,0 +1,54 @@
+import type { ApiErrorCode } from './errors.ts';
+import type { EventData, EventName } from './events.ts';
+import type { MethodName, MethodRequest } from './methods.ts';
+export interface RequestMessage<M extends MethodName = MethodName> {
+    kind: 'request';
+    /** Correlation id, echoed on the response. Non-empty, client-chosen. */
+    id: string;
+    method: M;
+    params?: MethodRequest<M>;
+}
+/** First message on every connection; carries the protocol version to compare against. */
+export interface HelloMessage {
+    kind: 'hello';
+    protocol: number;
+    app: {
+        name: string;
+        version: string;
+        platform: string;
+    };
+}
+export interface ResponseMessage {
+    kind: 'response';
+    id: string;
+    result: unknown;
+}
+/** `id` is null when the failure has no request to blame (unparseable frame). */
+export interface ErrorMessage {
+    kind: 'error';
+    id: string | null;
+    code: ApiErrorCode;
+    message: string;
+}
+export interface EventMessage<E extends EventName = EventName> {
+    kind: 'event';
+    event: E;
+    data: EventData<E>;
+}
+export type ServerMessage = HelloMessage | ResponseMessage | ErrorMessage | EventMessage;
+export type ClientMessage = RequestMessage;
+/**
+ * Parse one inbound client frame. Returns the request, or an error code telling
+ * the server what to answer: `parse-error` for junk bytes, `invalid-request`
+ * (with the id when one was salvageable) for a malformed envelope.
+ */
+export declare function parseClientMessage(raw: string): {
+    ok: true;
+    message: RequestMessage;
+} | {
+    ok: false;
+    code: 'parse-error' | 'invalid-request';
+    id: string | null;
+};
+/** Parse one inbound server frame; null for anything that is not a known server message. */
+export declare function parseServerMessage(raw: string): ServerMessage | null;

package/dist/envelope.js

@@ -0,0 +1,71 @@
+import { isApiErrorCode } from "./errors.js";
+import { isEventName } from "./events.js";
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * Parse one inbound client frame. Returns the request, or an error code telling
+ * the server what to answer: `parse-error` for junk bytes, `invalid-request`
+ * (with the id when one was salvageable) for a malformed envelope.
+ */
+export function parseClientMessage(raw) {
+    let v;
+    try {
+        v = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, code: 'parse-error', id: null };
+    }
+    if (!isRecord(v))
+        return { ok: false, code: 'invalid-request', id: null };
+    const id = typeof v.id === 'string' && v.id !== '' ? v.id : null;
+    if (v.kind !== 'request' || id === null)
+        return { ok: false, code: 'invalid-request', id };
+    if (typeof v.method !== 'string' || v.method === '')
+        return { ok: false, code: 'invalid-request', id };
+    if (v.params !== undefined && !isRecord(v.params))
+        return { ok: false, code: 'invalid-request', id };
+    return {
+        ok: true,
+        message: { kind: 'request', id, method: v.method, params: v.params },
+    };
+}
+/** Parse one inbound server frame; null for anything that is not a known server message. */
+export function parseServerMessage(raw) {
+    let v;
+    try {
+        v = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(v))
+        return null;
+    switch (v.kind) {
+        case 'hello': {
+            if (typeof v.protocol !== 'number' || !isRecord(v.app))
+                return null;
+            const { name, version, platform } = v.app;
+            if (typeof name !== 'string' || typeof version !== 'string' || typeof platform !== 'string')
+                return null;
+            return { kind: 'hello', protocol: v.protocol, app: { name, version, platform } };
+        }
+        case 'response':
+            if (typeof v.id !== 'string' || v.id === '')
+                return null;
+            return { kind: 'response', id: v.id, result: v.result };
+        case 'error': {
+            if (v.id !== null && (typeof v.id !== 'string' || v.id === ''))
+                return null;
+            if (!isApiErrorCode(v.code))
+                return null;
+            return { kind: 'error', id: v.id, code: v.code, message: typeof v.message === 'string' ? v.message : '' };
+        }
+        case 'event':
+            if (!isEventName(v.event))
+                return null;
+            return { kind: 'event', event: v.event, data: v.data };
+        default:
+            return null;
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,9 @@
+/** Every error the server can return, as string discriminants (never numeric bands). */
+export declare const API_ERROR_CODES: readonly ["parse-error", "invalid-request", "unknown-method", "invalid-params", "not-found", "unsupported-for-format", "conflict", "renderer-unavailable", "forbidden-path", "invalid-state", "internal"];
+export type ApiErrorCode = (typeof API_ERROR_CODES)[number];
+export declare function isApiErrorCode(v: unknown): v is ApiErrorCode;
+/** Thrown by {@link PersonaClient.call} when the server answers with an error envelope. */
+export declare class PersonaApiError extends Error {
+    readonly code: ApiErrorCode;
+    constructor(code: ApiErrorCode, message: string);
+}

package/dist/errors.js

@@ -0,0 +1,32 @@
+/** Every error the server can return, as string discriminants (never numeric bands). */
+export const API_ERROR_CODES = [
+    'parse-error',
+    'invalid-request',
+    'unknown-method',
+    'invalid-params',
+    /** A referenced id (scene, instance, model, asset, hotkey) resolves to nothing. */
+    'not-found',
+    /** The instance's model format cannot perform this method (e.g. MToon on Live2D). */
+    'unsupported-for-format',
+    /** Another session holds the injection lease for this parameter. */
+    'conflict',
+    /** The stage is not available to answer (no window, renderer reloading, or timeout). */
+    'renderer-unavailable',
+    /** The path is outside every user-configured plugin folder. */
+    'forbidden-path',
+    /** The operation is not allowed in the current state (e.g. deleting the last scene). */
+    'invalid-state',
+    'internal',
+];
+export function isApiErrorCode(v) {
+    return typeof v === 'string' && API_ERROR_CODES.includes(v);
+}
+/** Thrown by {@link PersonaClient.call} when the server answers with an error envelope. */
+export class PersonaApiError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'PersonaApiError';
+        this.code = code;
+    }
+}