@vespura/vmenu-plugin 0.0.0-stage → 1.0.8

package/dist/types/protocol.d.ts

@@ -0,0 +1,270 @@
+export declare const PROTOCOL_VERSION = 2;
+export declare const SERVER_PROTOCOL_VERSION = 1;
+export declare const VMENU_RESOURCE = "vMenu.Enhanced";
+export declare const PluginEvents: {
+    readonly Probe: 'vMenu.Enhanced:Plugins:Probe';
+    readonly Register: 'vMenu.Enhanced:Plugins:Register';
+    readonly Unregister: 'vMenu.Enhanced:Plugins:Unregister';
+    readonly Update: 'vMenu.Enhanced:Plugins:Update';
+    readonly Notify: 'vMenu.Enhanced:Plugins:Notify';
+    readonly Prompt: 'vMenu.Enhanced:Plugins:Prompt';
+    readonly SetTheme: 'vMenu.Enhanced:Plugins:SetTheme';
+    readonly RegisterThemes: 'vMenu.Enhanced:Plugins:RegisterThemes';
+    readonly Ready: 'vMenu.Enhanced:Plugins:Ready';
+    readonly ServerProbe: 'vMenu.Enhanced:Plugins:Server:Probe';
+    readonly ServerRegister: 'vMenu.Enhanced:Plugins:Server:Register';
+    readonly ServerDenied: 'vMenu.Enhanced:Plugins:Server:Denied';
+    readonly ServerReady: 'vMenu.Enhanced:Plugins:Server:Ready';
+    readonly readyFor: (resource: string) => string;
+    readonly registerResultFor: (resource: string) => string;
+    readonly eventFor: (resource: string) => string;
+    readonly promptResultFor: (resource: string) => string;
+    readonly themesFor: (resource: string) => string;
+    readonly themesRegisteredFor: (resource: string) => string;
+    readonly serverReadyFor: (resource: string) => string;
+    readonly serverRegisterResultFor: (resource: string) => string;
+};
+export declare const RefreshPermissionsEvent = "vMenu.Enhanced:Permissions:Refresh";
+export declare const EntryTypes: {
+    readonly Button: 'button';
+    readonly Checkbox: 'checkbox';
+    readonly List: 'list';
+    readonly Slider: 'slider';
+    readonly DynamicList: 'dynamicList';
+    readonly Submenu: 'submenu';
+    readonly Separator: 'separator';
+    readonly ConfirmButton: 'confirmButton';
+    readonly ConfirmList: 'confirmList';
+};
+export declare const NodeEvents: {
+    readonly Opened: 'opened';
+    readonly Closed: 'closed';
+    readonly IndexChanged: 'indexChanged';
+    readonly Highlighted: 'highlighted';
+};
+export declare const SettingTypes: {
+    readonly Bool: 'bool';
+    readonly Int: 'int';
+    readonly Float: 'float';
+    readonly String: 'string';
+};
+export declare const CallbackTypes: {
+    readonly ItemSelected: 'itemSelected';
+    readonly CheckboxChanged: 'checkboxChanged';
+    readonly ListIndexChanged: 'listIndexChanged';
+    readonly ListSelected: 'listSelected';
+    readonly SliderMoved: 'sliderMoved';
+    readonly SliderSelected: 'sliderSelected';
+    readonly DynamicSelected: 'dynamicSelected';
+    readonly DynamicChanging: 'dynamicChanging';
+    readonly Confirmed: 'confirmed';
+    readonly ItemHighlighted: 'itemHighlighted';
+    readonly MenuOpened: 'menuOpened';
+    readonly MenuClosed: 'menuClosed';
+    readonly MenuIndexChanged: 'menuIndexChanged';
+    readonly PlayerActionSelected: 'playerActionSelected';
+    readonly PlayerActionConfirmed: 'playerActionConfirmed';
+    readonly PlayerActionListSelected: 'playerActionListSelected';
+    readonly KeyPressed: 'keyPressed';
+};
+export declare const UpdateOps: {
+    readonly SetText: 'setText';
+    readonly SetDescription: 'setDescription';
+    readonly SetLabel: 'setLabel';
+    readonly SetLockedDescription: 'setLockedDescription';
+    readonly SetConfirmationDescription: 'setConfirmationDescription';
+    readonly SetIcons: 'setIcons';
+    readonly SetChecked: 'setChecked';
+    readonly SetOptions: 'setOptions';
+    readonly SetSelectedIndex: 'setSelectedIndex';
+    readonly SetSliderPosition: 'setSliderPosition';
+    readonly SetValue: 'setValue';
+    readonly SetVisible: 'setVisible';
+    readonly SetEnabled: 'setEnabled';
+    readonly SetGate: 'setGate';
+    readonly SetLog: 'setLog';
+    readonly SetBehaviour: 'setBehaviour';
+    readonly SetItemEvents: 'setItemEvents';
+    readonly AddItems: 'addItems';
+    readonly RemoveItems: 'removeItems';
+    readonly ClearMenu: 'clearMenu';
+    readonly MoveItem: 'moveItem';
+    readonly AddPlayerActions: 'addPlayerActions';
+    readonly SetMenuTitle: 'setMenuTitle';
+    readonly SetMenuSubtitle: 'setMenuSubtitle';
+    readonly OpenMenu: 'openMenu';
+    readonly CloseMenu: 'closeMenu';
+    readonly SelectItem: 'selectItem';
+    readonly SetMenuEvents: 'setMenuEvents';
+    readonly SetFilter: 'setFilter';
+    readonly ClearFilter: 'clearFilter';
+    readonly AddKeys: 'addKeys';
+    readonly SetKeyText: 'setKeyText';
+    readonly SetKeyEnabled: 'setKeyEnabled';
+    readonly SetKeyGate: 'setKeyGate';
+    readonly MergeTranslations: 'mergeTranslations';
+};
+export interface TextRef {
+    text?: string;
+    key?: string;
+    args?: Record<string, TextRef>;
+}
+export interface GateNode {
+    permission?: string;
+    setting?: string;
+    all?: GateNode[];
+    any?: GateNode[];
+}
+export interface ItemNode {
+    id: string;
+    type: string;
+    text?: TextRef;
+    description?: TextRef;
+    label?: TextRef;
+    lockedDescription?: TextRef;
+    gate?: GateNode;
+    behaviour?: string;
+    leftIcon?: string;
+    rightIcon?: string;
+    events?: string[];
+    visible?: boolean;
+    enabled?: boolean;
+    log?: boolean;
+    checked?: boolean;
+    checkStyle?: string;
+    options?: TextRef[];
+    selectedIndex?: number;
+    min?: number;
+    max?: number;
+    position?: number;
+    showDivider?: boolean;
+    value?: string;
+    confirmationDescription?: TextRef;
+    menu?: MenuNode;
+}
+export interface KeyNode {
+    id: string;
+    text?: TextRef;
+    description?: TextRef;
+    defaultKey: string;
+    defaultButton?: string;
+    shadowedControl?: number;
+    gate?: GateNode;
+    enabled?: boolean;
+}
+export interface MenuNode {
+    id: string;
+    title?: TextRef;
+    subtitle?: TextRef;
+    events?: string[];
+    items: ItemNode[];
+    keys?: KeyNode[];
+}
+export interface SettingNode {
+    name: string;
+    type: string;
+    default: string;
+    description: string;
+}
+export interface UpdateOp {
+    op: string;
+    itemId?: string;
+    menuId?: string;
+    keyId?: string;
+    textValue?: TextRef;
+    leftIcon?: string;
+    rightIcon?: string;
+    flag?: boolean;
+    index?: number;
+    value?: string;
+    options?: TextRef[];
+    gate?: GateNode;
+    items?: ItemNode[];
+    itemIds?: string[];
+    beforeItemId?: string;
+    events?: string[];
+    keys?: KeyNode[];
+    language?: string;
+    entries?: Record<string, string>;
+}
+export interface PluginCallback {
+    type: string;
+    menuId?: string;
+    itemId?: string;
+    keyId?: string;
+    disabledItemId?: string;
+    checked?: boolean;
+    oldIndex?: number;
+    newIndex?: number;
+    selectedIndex?: number;
+    oldPosition?: number;
+    newPosition?: number;
+    position?: number;
+    value?: string;
+    currentValue?: string;
+    left?: boolean;
+    targetServerId?: number;
+    targetName?: string;
+}
+export interface RegisterRequest {
+    protocolVersion: number;
+    displayName?: TextRef;
+    descriptionKey?: string;
+    translations?: Record<string, Record<string, string>>;
+    settings?: SettingNode[];
+    menu?: MenuNode;
+    playerActions?: ItemNode[];
+}
+/** vMenu's answer to a registration. Errors mean it was refused, warnings mean it was accepted with parts skipped. */
+export interface RegisterResult {
+    /** Whether vMenu took the registration. */
+    accepted: boolean;
+    /** The protocol version vMenu speaks. */
+    protocolVersion: number;
+    /** Why the registration was refused. */
+    errors: string[];
+    /** What vMenu skipped while accepting it. */
+    warnings: string[];
+}
+export interface PromptRequest {
+    requestId: number;
+    prompts: {
+        title?: TextRef;
+        maxLength: number;
+        initial: string;
+        suggestions?: {
+            value: string;
+            description?: string;
+        }[];
+    }[];
+}
+export interface PromptResult {
+    requestId: number;
+    cancelled: boolean;
+    busy: boolean;
+    answers?: string[];
+}
+export interface ThemeList {
+    themes?: {
+        id: string;
+        name: string;
+    }[];
+    current?: string;
+    configured?: string;
+    overridden?: boolean;
+}
+export interface ServerRegisterRequest {
+    protocolVersion: number;
+    displayName: string;
+    permissions?: {
+        name: string;
+        description: string;
+        staffOnly: boolean;
+    }[];
+    settings?: SettingNode[];
+    loggedItems?: {
+        itemId: string;
+        description: string;
+    }[];
+}
+export declare function normalizeResult(raw: Partial<RegisterResult> | undefined): RegisterResult | undefined;

package/dist/types/server/declaration.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Everything a plugin's server side declares with vMenu: a display name for the generated example
+ * files, the permission names it wants under its own scope, and the convar settings vMenu should
+ * describe to server owners. Names are short: vMenu composes the full
+ * `vMenu.Enhanced.Plugins.<Id>.<Name>` form from the resource name.
+ */
+export declare class ServerPluginDeclaration {
+    readonly displayName: string;
+    private readonly permissions;
+    private readonly settings;
+    private readonly loggedItems;
+    /** @param displayName Used in the generated example files, so owners see which plugin a section belongs to. */
+    constructor(displayName: string);
+    /** Declares a permission. `staffOnly` marks it as staff only in the generated permissions example. */
+    addPermission(name: string, description: string, staffOnly?: boolean): this;
+    /**
+     * Lets the server owner see a line in their webhook whenever somebody uses this row. The client
+     * half still has to set `log` on it. `description` is a noun phrase dropped into vMenu's own
+     * wording, as in "turned the anti-grief shield on".
+     */
+    addLoggedItem(itemId: string, description: string): this;
+    /** Declares an on or off setting. */
+    addBoolSetting(name: string, defaultValue: boolean, description: string): this;
+    /** Declares a whole number setting. */
+    addIntSetting(name: string, defaultValue: number, description: string): this;
+    /** Declares a decimal number setting. */
+    addFloatSetting(name: string, defaultValue: number, description: string): this;
+    /** Declares a text setting. */
+    addStringSetting(name: string, defaultValue: string, description: string): this;
+    private add;
+}

package/dist/types/server/index.d.ts

@@ -0,0 +1,5 @@
+export { version } from '../version.js';
+export type { Unsubscribe } from '../signal.js';
+export type { RegisterResult } from '../protocol.js';
+export { ServerPluginDeclaration } from './declaration.js';
+export { VMenuServer } from './server.js';

package/dist/types/server/server.d.ts

@@ -0,0 +1,30 @@
+import { type RegisterResult } from '../protocol.js';
+import { type Unsubscribe } from '../signal.js';
+import type { ServerPluginDeclaration } from './declaration.js';
+/**
+ * The server side entry point for a plugin. Call `register` once at startup; registering again
+ * after a vMenu restart happens by itself. Then use `isPlayerAllowed` to check the permissions you declared.
+ */
+export declare const VMenuServer: {
+    /**
+     * Declares the plugin with vMenu. The promise resolves on vMenu's first answer, which can be a
+     * while when vMenu starts later than the plugin. It never rejects: a refusal arrives as a result
+     * with `accepted` false.
+     */
+    register(pluginDeclaration: ServerPluginDeclaration): Promise<RegisterResult>;
+    /**
+     * Whether a player holds one of the plugin's own permissions, by its short name. Also honours the
+     * container grants a server owner may have used instead of the exact name.
+     */
+    isPlayerAllowed(playerSource: string | number, permissionName: string): boolean;
+    /**
+     * The same check as `isPlayerAllowed`, but a refusal is also reported to vMenu's security webhook.
+     * Use it where a legitimate client could only ever have sent the thing you are handling while
+     * allowed, and keep `isPlayerAllowed` for ordinary branching.
+     */
+    requirePermission(playerSource: string | number, permissionName: string): boolean;
+    /** Refreshes permissions for one or more players. Passing no ids refreshes every connected player. */
+    refreshPermissions(...serverIds: number[]): void;
+    /** Called on every registration answer, including automatic re-registrations. */
+    onRegistrationAnswered(handler: (result: RegisterResult) => void): Unsubscribe;
+};

package/dist/types/signal.d.ts

@@ -0,0 +1,12 @@
+/** Call it to stop receiving the event you subscribed to. */
+export type Unsubscribe = () => void;
+export declare class Signal<T extends unknown[]> {
+    private readonly resource;
+    private readonly name;
+    private handlers;
+    constructor(resource: () => string, name: string);
+    get hasHandlers(): boolean;
+    add(handler: (...args: T) => void): Unsubscribe;
+    fire(...args: T): void;
+}
+export declare function describe(error: unknown): string;

package/dist/types/text.d.ts

@@ -0,0 +1,20 @@
+/** Anything that can be shown as text: a plain string is a literal, a {@link Text} can also be a translation key. */
+export type TextLike = string | Text;
+/**
+ * A piece of display text, either a literal or a key into your plugin's translation tables. A plain
+ * string is a literal, so translating is always deliberate. vMenu resolves keys against the tables
+ * you registered, following its selected language with your English table as the fallback.
+ */
+export declare class Text {
+    private readonly value;
+    private readonly isKey;
+    private readonly args?;
+    private constructor();
+    /** Text shown exactly as written, never translated. */
+    static literal(text: string): Text;
+    /**
+     * A translation key, optionally with named placeholder values. In the translated string,
+     * `{name}` is replaced with the matching value, which can itself be a literal or another key.
+     */
+    static key(key: string, args?: Record<string, TextLike>): Text;
+}

package/dist/types/version.d.ts

@@ -0,0 +1,2 @@
+/** The vMenu Enhanced version this library was built for. */
+export declare const version: string;