@anvil-js/client 0.0.1

package/dist/ws/index.d.ts

@@ -0,0 +1,298 @@
+interface Packet {
+    type: string;
+    id: string;
+    payload: any;
+}
+declare class ConnectionCodec {
+    /** typeId → packetName (frames we receive) */
+    private incoming;
+    /** packetName → typeId (frames we send) */
+    private outgoing;
+    private nextOutgoingTypeId;
+    constructor();
+    /**
+     * Decode a single binary frame. Returns null for registration
+     * frames (which mutate the codec in place) and for unknown
+     * typeIds.
+     */
+    decode(buffer: ArrayBuffer | Uint8Array): Packet | null;
+    /**
+     * Encode a packet to a binary frame. If the packet name has
+     * not been registered yet, a fresh typeId is allocated and
+     * a registration frame is yielded first.
+     */
+    encode(name: string, payload: any, id?: string): Uint8Array[];
+    /** Register a packet type up-front (returns the typeId assigned). */
+    registerOutgoing(name: string): number;
+}
+
+/**
+ * Anvil WebSocket client  --  speaks the Essential Mod binary
+ * protocol over a single WebSocket connection.
+ *
+ * High-level API is a thin wrapper around the codec: every
+ * Essential Mod packet type has a corresponding `send*` method
+ * that returns a Promise resolving with the response packet
+ * (matched by packet id).
+ *
+ * Plus a typed event emitter for server-initiated packets
+ * (chat messages, friend status changes, profile updates, etc.)
+ * so React components can subscribe to live state.
+ */
+
+interface AnvilWsConfig {
+    /** WebSocket URL, e.g. "ws://localhost:3001/v1" */
+    url: string;
+    /** User UUID (sent as `essential-user-uuid` header). */
+    userUuid: string;
+    /** Username (sent as `essential-user-name` header). */
+    userName: string;
+    /** Max protocol version we understand. Default: 9. */
+    maxProtocolVersion?: number;
+    /** Authentication token (sent as `essential-authentication-token`). */
+    authenticationToken?: string;
+    /** Auto-reconnect on close. Default: true. */
+    autoReconnect?: boolean;
+    /** Reconnect delay in ms. Default: 2000. */
+    reconnectDelayMs?: number;
+}
+interface ChatMessage {
+    id: number;
+    channelId: number;
+    senderUuid: string;
+    content: string;
+    replyToId: number | null;
+    editedAt: number | null;
+    deleted: boolean;
+    createdAt: number;
+}
+interface ProfileStatus {
+    uuid: string;
+    status: 'ONLINE' | 'OFFLINE' | 'AWAY' | 'BUSY';
+    lastOnlineTimestamp: number;
+}
+interface FriendRelationship {
+    userA: string;
+    userB: string;
+    type: 'FRIENDS' | 'BLOCKED' | 'NEUTRAL';
+    status: 'PENDING' | 'VERIFIED';
+    since: number;
+}
+interface AnvilWsEvents {
+    open: void;
+    close: {
+        code: number;
+        reason: string;
+    };
+    error: Error;
+    bootstrap: void;
+    chat: ChatMessage & {
+        channelId: number;
+    };
+    friendAdded: FriendRelationship;
+    friendRemoved: {
+        userA: string;
+        userB: string;
+        type: string;
+    };
+    profileStatus: ProfileStatus;
+    profileActivity: {
+        uuid: string;
+        activity: string;
+        metadata: any;
+    };
+    cosmeticAnimation: {
+        userUuid: string;
+        cosmeticId: string;
+        animationId: string;
+    };
+    notice: {
+        id: string;
+        title: string;
+        body: string;
+        category: string;
+    };
+    serverList: {
+        recommended: any[];
+        featured: any[];
+    };
+    cosmeticsUnlocked: {
+        userUuid: string;
+        unlockedIds: string[];
+        gifted: boolean;
+        unlockMap: Record<string, any>;
+    };
+    equippedUpdate: {
+        userUuid: string;
+        equipped: Record<string, string>;
+    };
+    playerSettings: {
+        userUuid: string;
+        settings: Record<string, any>;
+    };
+    skinTexture: {
+        userUuid: string;
+        skinTexture: string | null;
+    };
+    upnpSession: {
+        hostUuid: string;
+        ip: string;
+        port: number;
+        privacy: string;
+        worldName: string | null;
+        protocolVersion: number | null;
+        invites: string[];
+        createdAt: number;
+        rawStatus: string | null;
+    };
+    upnpSessionRemoved: {
+        hostUuid: string;
+    };
+    upnpInvite: {
+        hostUuid: string;
+    };
+    raw: Packet;
+}
+type Listener<T> = (data: T) => void;
+declare class AnvilWsClient {
+    private ws;
+    private codec;
+    private config;
+    private listeners;
+    private pendingRequests;
+    private state;
+    private bootstrapReceived;
+    private reconnectTimer;
+    private defaultRequestTimeoutMs;
+    constructor(config: AnvilWsConfig);
+    connect(): Promise<void>;
+    disconnect(): void;
+    private scheduleReconnect;
+    private preRegisterOutgoing;
+    private handleFrame;
+    private dispatch;
+    private sendRequest;
+    sendChatMessage(channelId: number, content: string, replyToId?: number): Promise<Packet & {
+        payload: any;
+    }>;
+    retrieveChatMessages(channelId: number, limit?: number, beforeMessageId?: number): Promise<Packet & {
+        payload: any;
+    }>;
+    createChannel(type: 'DIRECT_MESSAGE' | 'GROUP_DIRECT_MESSAGE' | 'ANNOUNCEMENT', name: string, memberUuids?: string[]): Promise<Packet & {
+        payload: any;
+    }>;
+    deleteChatMessage(messageId: number): Promise<Packet & {
+        payload: any;
+    }>;
+    addFriend(targetUuid: string): Promise<Packet & {
+        payload: any;
+    }>;
+    removeFriend(targetUuid: string): Promise<Packet & {
+        payload: any;
+    }>;
+    blockUser(targetUuid: string): Promise<Packet & {
+        payload: any;
+    }>;
+    lookupUuidByName(username: string): Promise<Packet & {
+        payload: any;
+    }>;
+    getProfile(uuid: string): Promise<Packet & {
+        payload: any;
+    }>;
+    setActivity(activity: string, metadata?: any): Promise<Packet & {
+        payload: any;
+    }>;
+    listCosmetics(): Promise<Packet & {
+        payload: any;
+    }>;
+    triggerCosmeticAnimation(cosmeticId: string, animationId: string): Promise<Packet & {
+        payload: any;
+    }>;
+    unlockCosmetics(cosmeticIds: string[]): Promise<Packet & {
+        payload: any;
+    }>;
+    createSkin(name: string, model: 'CLASSIC' | 'SLIM', hash: string): Promise<Packet & {
+        payload: any;
+    }>;
+    selectLastUsedSkin(skinId: string): Promise<Packet & {
+        payload: any;
+    }>;
+    favoriteSkin(skinId: string, favorited: boolean): Promise<Packet & {
+        payload: any;
+    }>;
+    createOutfit(name: string, equippedCosmetics: Record<string, string>, settings?: Record<string, any>): Promise<Packet & {
+        payload: any;
+    }>;
+    selectOutfit(outfitId: string): Promise<Packet & {
+        payload: any;
+    }>;
+    setEquippedCosmetic(outfitId: string, slot: string, cosmeticId: string): Promise<Packet & {
+        payload: any;
+    }>;
+    updateEmoteWheel(wheelId: string, slots: Record<string, string>): Promise<Packet & {
+        payload: any;
+    }>;
+    selectEmoteWheel(wheelId: string): Promise<Packet & {
+        payload: any;
+    }>;
+    getWardrobeSettings(): Promise<Packet & {
+        payload: any;
+    }>;
+    listNotices(): Promise<Packet & {
+        payload: any;
+    }>;
+    listServerDiscovery(): Promise<Packet & {
+        payload: any;
+    }>;
+    listKnownServers(): Promise<Packet & {
+        payload: any;
+    }>;
+    relayIcePacket(targetUuid: string, payload: Uint8Array): Promise<Packet & {
+        payload: any;
+    }>;
+    pingServer(host: string, port: number, protocolVersion?: number): Promise<Packet & {
+        payload: any;
+    }>;
+    createSession(ip: string, port: number, privacy: 'PUBLIC' | 'FRIENDS' | 'INVITE_ONLY', worldName?: string, protocolVersion?: number): Promise<Packet & {
+        payload: any;
+    }>;
+    closeSession(): Promise<Packet & {
+        payload: any;
+    }>;
+    updateSession(patch: {
+        ip?: string;
+        port?: number;
+        privacy?: 'PUBLIC' | 'FRIENDS' | 'INVITE_ONLY';
+    }): Promise<Packet & {
+        payload: any;
+    }>;
+    inviteToSession(inviteeUuids: string[]): Promise<Packet & {
+        payload: any;
+    }>;
+    revokeSessionInvites(inviteeUuids: string[]): Promise<Packet & {
+        payload: any;
+    }>;
+    pushServerStatus(rawStatus: string): Promise<Packet & {
+        payload: any;
+    }>;
+    inviteFriendToServer(targetUuid: string, address: string): Promise<Packet & {
+        payload: any;
+    }>;
+    on<K extends keyof AnvilWsEvents>(event: K, listener: Listener<AnvilWsEvents[K]>): () => void;
+    off<K extends keyof AnvilWsEvents>(event: K, listener: Listener<AnvilWsEvents[K]>): void;
+    private emit;
+    isReady(): boolean;
+    isConnected(): boolean;
+}
+/**
+ * Subscribe to a WS event in a React component. The subscription
+ * is cleaned up automatically on unmount.
+ */
+declare function useWsEvent<K extends keyof AnvilWsEvents>(client: AnvilWsClient, event: K, handler: Listener<AnvilWsEvents[K]>): void;
+/**
+ * Track connection state for a WS client. Returns the current
+ * state ('disconnected' | 'connecting' | 'connected' | 'ready').
+ */
+declare function useWsState(client: AnvilWsClient): AnvilWsClient['state'] | 'disconnected';
+
+export { AnvilWsClient, type AnvilWsConfig, type AnvilWsEvents, type ChatMessage, ConnectionCodec, type FriendRelationship, type Packet, type ProfileStatus, useWsEvent, useWsState };