@shaunlwm/pickle.ts 1.10.0 → 1.11.0

package/dist/index.d.ts

@@ -1,4 +1,3 @@
-import * as socket_io_client from 'socket.io-client';
 import { Socket, ManagerOptions, SocketOptions } from 'socket.io-client';
 import { EventEmitter } from 'node:events';
 
@@ -50,6 +49,55 @@ type QueueUpdate = {
     queueLength: number;
 };
 
+type ClientLifecyclePhase = "transport_connecting" | "queueing" | "authenticating" | "joining_session" | "awaiting_initial_state" | "ready" | "disconnecting" | "disconnected";
+type ClientLifecycleUpdate = {
+    phase: ClientLifecyclePhase;
+    occurredAt: number;
+    queue?: QueueUpdate;
+};
+type ClientOperationOptions = {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+};
+type ClientConnectionTimeouts = {
+    loginMs: number;
+    transportMs: number;
+    /** Maximum silence between queue updates, not total time spent queued. */
+    queueMs: number;
+    authenticationMs: number;
+    initialStateMs: number;
+    requestMs: number;
+};
+declare const DEFAULT_CLIENT_CONNECTION_TIMEOUTS: {
+    readonly loginMs: 20000;
+    readonly transportMs: 20000;
+    readonly queueMs: 300000;
+    readonly authenticationMs: 20000;
+    readonly initialStateMs: 15000;
+    readonly requestMs: 15000;
+};
+type ClientDisconnectInfo = {
+    intentional: boolean;
+    reason: string | null;
+    occurredAt: number;
+};
+
+type ClientOperationErrorCategory = "login_timeout" | "login_rejected" | "invalid_credentials" | "account_banned" | "queue_timeout" | "transport_error" | "auth_timeout" | "auth_failed" | "initial_state_timeout" | "operation_timeout" | "unsupported_operation" | "aborted" | "disconnected" | "kicked" | "server_error";
+type ClientOperationErrorOptions = {
+    category: ClientOperationErrorCategory;
+    phase: ClientLifecyclePhase;
+    retryable: boolean;
+    message: string;
+    cause?: unknown;
+};
+declare function sanitizeClientErrorMessage(message: string): string;
+declare class ClientOperationError extends Error {
+    readonly category: ClientOperationErrorCategory;
+    readonly phase: ClientLifecyclePhase;
+    readonly retryable: boolean;
+    constructor(options: ClientOperationErrorOptions);
+}
+
 /** Core appearance slots shared by all servers (CPJourney, CPLegacy, NewCP). */
 type PlayerAppearance = {
     color: number;
@@ -102,7 +150,24 @@ type RoomUser = PlayerAppearance & {
     x: number;
     y: number;
     frame: number;
-    /** Adapter-specific extras. See each adapter's normalizeUser for keys. */
+    /**
+     * Adapter-specific extras. See each adapter's normalizeUser for keys.
+     *
+     * **CPJourney** overlay appearance slots (number):
+     * `hat`, `face_mask`, `neck_scarf`, `body_shirt`, `hand_glove`
+     *
+     * **CPJourney** user state:
+     * `transform` (number) — costume ID, 0 = none
+     * `walkingPuffleType` (number | null) — puffle species
+     * `openSprite` (string | null) — sprite state e.g. "1_3"
+     * `mascotGiveaway` (number | null) — non-null = mascot, value = giveaway item ID
+     * `iglooOpen` (number) — 0/1
+     * `iglooBounds` (number) — 0/1
+     * `igloo_slot` (number) — active igloo slot
+     * `currentLayer` (number) — rendering layer
+     * `fireRank` (number) — fire ninja rank 0–5
+     * `isInvisible` (boolean) — mascot visibility flag
+     */
     meta: Record<string, unknown>;
     /** Original unnormalized server response */
     _raw: Record<string, unknown>;
@@ -144,7 +209,78 @@ type Postcard = {
     senderId: number;
     postcardId: number;
     extra: string | null;
-    date: string;
+    /** CPJourney MessagePack decodes this as a Date; other adapters may use strings. */
+    date: Date | string;
+};
+/** A puffle summary, optionally including CPJourney's full care state. */
+type Puffle = {
+    id: number;
+    type: number;
+    userId?: number;
+    name?: string;
+    energy?: number;
+    health?: number;
+    rest?: number;
+    experience?: number;
+    level?: number;
+    adoption_date?: Record<string, unknown>;
+    last_feed?: Record<string, unknown>;
+    last_slept?: Record<string, unknown>;
+    postcard_hungry?: boolean;
+    dead?: number;
+    ran_away?: number;
+    last_dig?: number;
+    in_backyard?: number;
+    backyard_supplies?: number;
+    walking?: boolean;
+    backyard?: boolean;
+};
+/** CPJourney puffle care values returned by get_wellbeing/update_wellbeing. */
+type PuffleWellbeing = {
+    puffleId: number;
+    energy: number;
+    health: number;
+    rest: number;
+    name: string;
+    type: number;
+    level: number;
+    experience: number;
+    inBackyard?: number;
+    backyardSupplyCost?: number;
+    backyardSuppliesEmpty?: boolean;
+    backyardPuffleCount?: number;
+};
+/** Furniture placement sent by CPJourney's igloo editor. */
+type IglooFurniturePlacement = {
+    furnitureId: number;
+    x: number;
+    y: number;
+    rotation: number;
+    frame: number;
+    depth: number;
+    /** Present in join_igloo snapshots but omitted by editor updates. */
+    slot?: number;
+};
+/** Common CPJourney igloo/music store item fields. */
+type IglooStoreItem = {
+    id: string;
+    name: string;
+    cost: number;
+    store: number;
+    seasonal: number;
+    new: number;
+    active?: number;
+    patched?: number;
+    timeAdded?: number;
+};
+/** CPJourney furniture catalog item fields. */
+type FurnitureStoreItem = IglooStoreItem & {
+    type: number;
+    sort: number;
+    member: number;
+    bait: number;
+    max: number;
+    fps?: number;
 };
 type NinjaCard = {
     id: number;
@@ -204,8 +340,19 @@ type SocketIoConnectionOptions = Partial<ManagerOptions & SocketOptions> & {
     extraHeaders?: Record<string, string>;
     origin?: string;
 };
+type AdapterMessage = {
+    action: string;
+    args: Record<string, unknown>;
+};
 type ConnectOptions = {
+    signal?: AbortSignal;
+    timeouts?: Partial<ClientConnectionTimeouts>;
     onQueueUpdate?: (update: QueueUpdate) => void;
+    onLifecycleUpdate?: (update: ClientLifecycleUpdate) => void;
+    /** @internal Normalized message delivery installed before session join. */
+    onMessage?: (message: AdapterMessage) => void;
+    /** @internal Transport disconnect delivery installed before session join. */
+    onDisconnect?: (reason: string | null) => void;
 };
 declare abstract class BaseAdapter {
     protected readonly connectionProfile: NormalizedConnectionProfile;
@@ -214,10 +361,14 @@ declare abstract class BaseAdapter {
     loginMessage: string | null;
     loginStatus: "active" | "banned";
     constructor(connectionProfile?: NormalizedConnectionProfile);
-    abstract login(options: LoginOptions | TokenLoginOptions): Promise<LoginResult>;
+    abstract login(options: LoginOptions | TokenLoginOptions, operationOptions?: ClientOperationOptions): Promise<LoginResult>;
     abstract connect(serverName: string, loginResult: LoginResult, options?: ConnectOptions): Promise<Socket>;
     abstract disconnect(): void;
     abstract send(action: string, args: Record<string, unknown>): void;
+    protected connectionTimeouts(options?: ConnectOptions): ClientConnectionTimeouts;
+    protected reportLifecycle(options: ConnectOptions | undefined, phase: ClientLifecyclePhase, queue?: QueueUpdate): void;
+    protected resetLoginState(): void;
+    protected unsupportedOperation(operation: string): ClientOperationError;
     protected socketIoOptions(defaultUrlOrOrigin: string): SocketIoConnectionOptions;
     protected webSocketOptions(defaultUrlOrOrigin: string): {
         headers?: Record<string, string>;
@@ -250,6 +401,7 @@ declare abstract class BaseAdapter {
     buddyReject(_id: number): void;
     buddyRequestSeen(_id: number): void;
     getBuddy(_id: number, _type: "buddies" | "buddyRequests"): void;
+    findBuddy(_id: number): void;
     removeBuddy(_id: number): void;
     addIgnore(_id: number): void;
     removeIgnore(_id: number): void;
@@ -261,11 +413,48 @@ declare abstract class BaseAdapter {
     getPostcards(): void;
     getIglooOpen(_igloo: number): void;
     getIgloos(): void;
-    getPuffles(_userId: number): void;
+    getPuffles(_userId: number, _isBackyard?: boolean): void;
+    getAllPuffles(): void;
+    getPuffleWellbeing(_puffle: number): void;
+    playPuffle(_puffle: number): void;
+    restPuffle(_puffle: number): void;
+    buyPuffleItem(_puffleId: number, _item: number): void;
+    walkPuffle(_puffle: number): void;
+    initializePuffleTower(): void;
+    getBackyardSupplies(): void;
     adoptPuffle(_type: number, _name: string): void;
     getIglooLikes(): void;
     checkPuffleSprite(_puffleSprite: boolean): void;
     joinIgloo(_igloo: number, _x?: number, _y?: number): void;
+    getStoreMusic(): void;
+    buyMusic(_music: string): void;
+    getIglooStoreItems(): void;
+    buyFurniture(_furniture: string, _amount: number): void;
+    updateIglooMusic(_music: string): void;
+    updateIglooFurniture(_furniture: Array<{
+        furnitureId: number;
+        x: number;
+        y: number;
+        rotation: number;
+        frame: number;
+        depth: number;
+        slot?: number;
+    }>): void;
+    autoUpdateIglooFurniture(_furniture: Array<{
+        furnitureId: number;
+        x: number;
+        y: number;
+        rotation: number;
+        frame: number;
+        depth: number;
+        slot?: number;
+    }>): void;
+    updateIglooType(_type: number): void;
+    openIgloo(): void;
+    closeIglooBounds(): void;
+    likeIgloo(): void;
+    openIglooEditor(): void;
+    closeIglooEditor(): void;
     gameOver(_coins: number): void;
     collectStamp(_stamp: number): void;
     /** Fetch ninja rank, progress, and card deck. Listen for `get_ninja` event. */
@@ -288,7 +477,8 @@ declare abstract class BaseAdapter {
 
 declare class CpjourneyAdapter extends BaseAdapter {
     readonly id = "CPJourney";
-    login(options: LoginOptions | TokenLoginOptions): Promise<LoginResult>;
+    private gameToken;
+    login(options: LoginOptions | TokenLoginOptions, operationOptions?: ClientOperationOptions): Promise<LoginResult>;
     connect(serverName: string, loginResult: LoginResult, options?: ConnectOptions): Promise<Socket>;
     private queueForServer;
     send(action: string, args: Record<string, unknown>): void;
@@ -317,6 +507,7 @@ declare class CpjourneyAdapter extends BaseAdapter {
     buddyReject(id: number): void;
     buddyRequestSeen(id: number): void;
     getBuddy(id: number, type: "buddies" | "buddyRequests"): void;
+    findBuddy(id: number): void;
     removeBuddy(id: number): void;
     addIgnore(id: number): void;
     removeIgnore(id: number): void;
@@ -328,11 +519,48 @@ declare class CpjourneyAdapter extends BaseAdapter {
     getPostcards(): void;
     getIglooOpen(igloo: number): void;
     getIgloos(): void;
-    getPuffles(userId: number): void;
+    getPuffles(userId: number, isBackyard?: boolean): void;
+    getAllPuffles(): void;
+    getPuffleWellbeing(puffle: number): void;
+    playPuffle(puffle: number): void;
+    restPuffle(puffle: number): void;
+    buyPuffleItem(puffleId: number, item: number): void;
+    walkPuffle(puffle: number): void;
+    initializePuffleTower(): void;
+    getBackyardSupplies(): void;
     adoptPuffle(type: number, name: string): void;
     getIglooLikes(): void;
     checkPuffleSprite(puffleSprite: boolean): void;
     joinIgloo(igloo: number, x?: number, y?: number): void;
+    getStoreMusic(): void;
+    buyMusic(music: string): void;
+    getIglooStoreItems(): void;
+    buyFurniture(furniture: string, amount: number): void;
+    updateIglooMusic(music: string): void;
+    updateIglooFurniture(furniture: Array<{
+        furnitureId: number;
+        x: number;
+        y: number;
+        rotation: number;
+        frame: number;
+        depth: number;
+        slot?: number;
+    }>): void;
+    autoUpdateIglooFurniture(furniture: Array<{
+        furnitureId: number;
+        x: number;
+        y: number;
+        rotation: number;
+        frame: number;
+        depth: number;
+        slot?: number;
+    }>): void;
+    updateIglooType(type: number): void;
+    openIgloo(): void;
+    closeIglooBounds(): void;
+    likeIgloo(): void;
+    openIglooEditor(): void;
+    closeIglooEditor(): void;
     gameOver(coins: number): void;
     collectStamp(stamp: number): void;
     getNinja(): void;
@@ -343,13 +571,13 @@ declare class CpjourneyAdapter extends BaseAdapter {
     selectCard(slot: number): void;
     loadAnimation(animation: string): void;
     joinMat(waddle: number): void;
-    private createSocket;
+    protected createSocket(path: string): Socket;
 }
 
 declare class CplegacyAdapter extends BaseAdapter {
     readonly id = "CPLegacy";
     private version;
-    login(options: LoginOptions | TokenLoginOptions): Promise<LoginResult>;
+    login(options: LoginOptions | TokenLoginOptions, operationOptions?: ClientOperationOptions): Promise<LoginResult>;
     connect(serverName: string, loginResult: LoginResult, options?: ConnectOptions): Promise<Socket>;
     send(action: string, args: Record<string, unknown>): void;
     disconnect(): void;
@@ -385,48 +613,14 @@ declare class CplegacyAdapter extends BaseAdapter {
     gameOver(coins: number): void;
     collectStamp(stamp: number): void;
     private postLogin;
-}
-
-declare class CpzeroAdapter extends BaseAdapter {
-    readonly id = "CPZero";
-    private sfs;
-    login(options: LoginOptions | TokenLoginOptions): Promise<LoginResult>;
-    connect(_serverName: string, loginResult: LoginResult, _options?: ConnectOptions): Promise<socket_io_client.Socket>;
-    send(action: string, args: Record<string, unknown>): void;
-    disconnect(): void;
-    normalizeUser(raw: Record<string, unknown>): RoomUser;
-    normalizePlayer(raw: Record<string, unknown>): PlayerData;
-    sendMessage(message: string): void;
-    sendEmote(emote: number): void;
-    sendSafe(safe: number): void;
-    walk(x: number, y: number): void;
-    sendFrame(frame: number): void;
-    snowball(x: number, y: number): void;
-    joinRoom(room: number, x?: number, y?: number): void;
-    addItem(item: number): void;
-    equipColor(item: number): void;
-    equipHead(item: number): void;
-    equipFace(item: number): void;
-    equipNeck(item: number): void;
-    equipBody(item: number): void;
-    equipHand(item: number): void;
-    equipFeet(item: number): void;
-    equipFlag(item: number): void;
-    equipPhoto(item: number): void;
-    getPlayer(id: number): void;
-    joinIgloo(igloo: number, _x?: number, _y?: number): void;
-    /**
-     * Process a batch of `%xt%` messages that may be concatenated in a single
-     * WebSocket frame (separated by \0 already split, but multiple %xt% in one string).
-     */
-    private processXtBatch;
+    protected createSocket(serverName: string): Socket;
 }
 
 declare class NewcpAdapter extends BaseAdapter {
     readonly id = "NewCP";
     private encryptor;
     private worlds;
-    login(options: LoginOptions | TokenLoginOptions): Promise<LoginResult>;
+    login(options: LoginOptions | TokenLoginOptions, operationOptions?: ClientOperationOptions): Promise<LoginResult>;
     connect(serverName: string, loginResult: LoginResult, options?: ConnectOptions): Promise<Socket>;
     send(action: string, args: Record<string, unknown>): void;
     disconnect(): void;
@@ -457,13 +651,13 @@ declare class NewcpAdapter extends BaseAdapter {
     removeIgnore(id: number): void;
     getPlayer(id: number): void;
     joinIgloo(igloo: number, x?: number, y?: number): void;
-    private createSocket;
+    protected createSocket(host: string, path: string): Socket;
     private loadWorlds;
 }
 
 declare class PenguinoriginsAdapter extends BaseAdapter {
     readonly id = "PenguinOrigins";
-    login(options: LoginOptions | TokenLoginOptions): Promise<LoginResult>;
+    login(options: LoginOptions | TokenLoginOptions, operationOptions?: ClientOperationOptions): Promise<LoginResult>;
     connect(serverName: string, loginResult: LoginResult, options?: ConnectOptions): Promise<Socket>;
     send(action: string, args: Record<string, unknown>): void;
     disconnect(): void;
@@ -493,13 +687,12 @@ declare class PenguinoriginsAdapter extends BaseAdapter {
     getIglooOpen(igloo: number): void;
     joinIgloo(igloo: number, x?: number, y?: number): void;
     gameOver(coins: number): void;
-    private createSocket;
+    protected createSocket(path: string): Socket;
 }
 
 declare const ADAPTERS: {
     readonly CPJourney: typeof CpjourneyAdapter;
     readonly CPLegacy: typeof CplegacyAdapter;
-    readonly CPZero: typeof CpzeroAdapter;
     readonly NewCP: typeof NewcpAdapter;
     readonly PenguinOrigins: typeof PenguinoriginsAdapter;
 };
@@ -577,6 +770,7 @@ type ClientMessages = {
     get_igloos: Record<string, never>;
     get_puffles: {
         userId: number;
+        isBackyard?: boolean;
     };
     get_igloo_likes: Record<string, never>;
     join_igloo: {
@@ -628,6 +822,54 @@ type ClientMessages = {
     check_puffle_sprite: {
         puffleSprite: unknown;
     };
+    get_all_puffles: Record<string, never>;
+    get_wellbeing: {
+        puffle: number;
+    };
+    puffle_play: {
+        puffle: number;
+    };
+    update_puffle_rest: {
+        puffle: number;
+    };
+    puffle_buy_item: {
+        puffleId: number;
+        item: number;
+    };
+    walk_puffle: {
+        puffle: number;
+    };
+    backyard_supplies: Record<string, never>;
+    buddy_find: {
+        id: number;
+    };
+    get_store_music: Record<string, never>;
+    add_music: {
+        music: string;
+    };
+    get_igloostore_items: Record<string, never>;
+    add_furniture: {
+        furniture: string;
+        amount: number;
+    };
+    update_music: {
+        music: string;
+    };
+    update_furniture: {
+        furniture: IglooFurniturePlacement[];
+    };
+    update_furniture_auto: {
+        furniture: IglooFurniturePlacement[];
+    };
+    update_igloo: {
+        type: number;
+    };
+    open_igloo: Record<string, never>;
+    close_igloo_bounds: Record<string, never>;
+    like_igloo: Record<string, never>;
+    igloo_editor_open: Record<string, never>;
+    igloo_editor_closed: Record<string, never>;
+    tower_init: Record<string, never>;
     queue_server_join: {
         server: string;
     };
@@ -827,11 +1069,74 @@ type ServerMessages = {
     };
     get_puffles: {
         userId: number;
-        puffles: {
-            id: number;
-            type: number;
-        }[];
+        puffles: Puffle[];
+    };
+    get_all_puffles: {
+        puffles: Puffle[];
+    };
+    get_wellbeing: PuffleWellbeing;
+    get_walking_puffle: {
+        puffle: Puffle;
+    };
+    update_wellbeing: PuffleWellbeing;
+    puffle_levelup: {
+        puffleId: number;
+        level: number;
+    };
+    puffle_popup: {
+        puffleId: number;
+        popupId: number;
+    };
+    buy_puffle_item: {
+        puffleId: number;
+        item: number;
+        coins: number;
+        puffleInventory: Record<string, unknown>;
+    };
+    walk_puffle: {
+        user: number;
+        puffle: number;
+        type: number;
+    };
+    backyard_supplies: {
+        supplyCost: number;
+        puffleCount: number;
+        supplyState: number;
+    };
+    buddy_find: {
+        find: number;
+        username: string;
+        game: boolean;
+    };
+    receive_postcard: Postcard;
+    get_store_music: {
+        music: IglooStoreItem[];
+    };
+    add_music: {
+        music: string;
+        coins: number;
+    };
+    get_igloostore_items: {
+        furniture: FurnitureStoreItem[];
+        flooring: IglooStoreItem[];
+        igloo: IglooStoreItem[];
+        location: IglooStoreItem[];
+    };
+    add_furniture: {
+        furniture: string;
+        coins: number;
+        amount: number;
+    };
+    update_music: {
+        music: string;
+    };
+    igloo_open_status: {
+        status: number;
+    };
+    igloo_bounds_status: {
+        status: number;
     };
+    igloo_liked: Record<string, never>;
     update_player: {
         id: number;
         item: number;
@@ -878,7 +1183,7 @@ type ServerMessages = {
         transform: number;
     };
     adopt_puffle: {
-        puffle: unknown;
+        puffle?: unknown;
         coins: number;
     };
     /** Generic server info/notification message */
@@ -889,7 +1194,7 @@ type ServerMessages = {
         action: string;
         args: Record<string, unknown>;
     };
-    disconnect: undefined;
+    disconnect: ClientDisconnectInfo;
     /** Ninja rank, progress, and full card deck */
     get_ninja: NinjaData;
     /** State of all Dojo mats — keys are mat IDs, values are seat arrays */
@@ -954,26 +1259,30 @@ type ServerMessages = {
         message: string;
     };
 };
+/** CPJourney-only commands captured from its Socket.IO protocol. */
+type CpjourneyClientMessages = Pick<ClientMessages, "get_puffles" | "adopt_puffle" | "check_puffle_sprite" | "get_all_puffles" | "get_wellbeing" | "puffle_play" | "update_puffle_rest" | "puffle_buy_item" | "walk_puffle" | "backyard_supplies" | "buddy_find" | "get_store_music" | "add_music" | "get_igloostore_items" | "add_furniture" | "update_music" | "update_furniture" | "update_furniture_auto" | "update_igloo" | "open_igloo" | "close_igloo_bounds" | "like_igloo" | "igloo_editor_open" | "igloo_editor_closed" | "tower_init">;
+/** CPJourney-only events captured from its Socket.IO protocol. */
+type CpjourneyServerMessages = Pick<ServerMessages, "game_over" | "get_postcards" | "join_igloo" | "get_puffles" | "adopt_puffle" | "get_all_puffles" | "get_wellbeing" | "get_walking_puffle" | "update_wellbeing" | "puffle_levelup" | "puffle_popup" | "buy_puffle_item" | "walk_puffle" | "backyard_supplies" | "buddy_find" | "receive_postcard" | "get_store_music" | "add_music" | "get_igloostore_items" | "add_furniture" | "update_music" | "igloo_open_status" | "igloo_bounds_status" | "igloo_liked">;
 
-type WaitForFn = <K extends keyof ServerMessages>(event: K, timeout?: number) => Promise<ServerMessages[K]>;
+type RequestFn = <K extends keyof ServerMessages>(event: K, send: () => void, options?: ClientOperationOptions, matches?: (args: ServerMessages[K]) => boolean) => Promise<ServerMessages[K]>;
 declare class CardJitsu {
     private adapter;
-    private waitFor;
-    constructor(adapter: BaseAdapter, waitFor: WaitForFn);
+    private request;
+    constructor(adapter: BaseAdapter, request: RequestFn);
     /** Fetch ninja rank, progress, and card deck. Resolves with ninja data. */
-    getNinja(): Promise<ServerMessages["get_ninja"]>;
+    getNinja(options?: ClientOperationOptions): Promise<ServerMessages["get_ninja"]>;
     /** Fetch state of all Dojo mats. Resolves with mat state. */
-    getMats(): Promise<ServerMessages["get_waddles"]>;
+    getMats(options?: ClientOperationOptions): Promise<ServerMessages["get_waddles"]>;
     /** Sit on a Dojo mat to wait for an opponent. Listen for `update_waddle` events. */
     joinMat(waddle: number): void;
     /** Join Sensei matchmaking queue. Resolves when server acknowledges. */
-    joinMatchmaking(): Promise<ServerMessages["join_matchmaking"]>;
+    joinMatchmaking(options?: ClientOperationOptions): Promise<ServerMessages["join_matchmaking"]>;
     /** Leave Sensei matchmaking queue. */
     leaveMatchmaking(): void;
     /** Start a Card-Jitsu match after entering a game room. Resolves with player info. */
-    startGame(): Promise<ServerMessages["start_game"]>;
+    startGame(options?: ClientOperationOptions): Promise<ServerMessages["start_game"]>;
     /** Play a card from your hand by slot index. Resolves when server acknowledges. */
-    selectCard(slot: number): Promise<ServerMessages["move_my_card"]>;
+    selectCard(slot: number, options?: ClientOperationOptions): Promise<ServerMessages["move_my_card"]>;
     /** Preload a power card animation asset. */
     loadAnimation(animation: string): void;
 }
@@ -993,12 +1302,20 @@ declare class Client extends EventEmitter {
     private loginResult;
     private log;
     private _cardJitsu;
+    private intentionalDisconnect;
+    private disconnectNotified;
+    private connectionFailure;
+    private lifecycleReporter;
+    private requestTails;
+    private disconnectEpoch;
+    private lastDisconnectInfo;
     get loginMessage(): string | null;
     get loginStatus(): "active" | "banned";
     get cardJitsu(): CardJitsu;
     constructor(server: AdapterName, options?: ClientOptions);
-    login(options: LoginOptions | TokenLoginOptions): Promise<ServerInfo[]>;
+    login(options: LoginOptions | TokenLoginOptions, operationOptions?: ClientOperationOptions): Promise<ServerInfo[]>;
     connect(serverName: string, options?: ConnectOptions): Promise<void>;
+    private waitForInitialState;
     on<K extends keyof ServerMessages>(event: K, listener: ServerMessageHandler<K>): this;
     on(event: string, listener: (...args: unknown[]) => void): this;
     off<K extends keyof ServerMessages>(event: K, listener: ServerMessageHandler<K>): this;
@@ -1007,16 +1324,20 @@ declare class Client extends EventEmitter {
     once(event: string, listener: (...args: unknown[]) => void): this;
     emit<K extends keyof ServerMessages>(event: K, args: ServerMessages[K]): boolean;
     emit(event: string, ...args: unknown[]): boolean;
-    /** Wait for a server event. Resolves with the event payload. Optional timeout in ms. Rejects on disconnect. */
+    /** Wait for a server event. Resolves with the event payload and rejects on timeout, abort, or disconnect. */
     waitFor<K extends keyof ServerMessages>(event: K, timeout?: number): Promise<ServerMessages[K]>;
+    waitFor<K extends keyof ServerMessages>(event: K, options?: ClientOperationOptions): Promise<ServerMessages[K]>;
+    private waitForEvent;
+    private request;
+    private waitForRequestTurn;
     sendMessage(message: string): void;
     sendEmote(emote: number): void;
     sendSafe(safe: number): void;
     walk(x: number, y: number): void;
     sendFrame(frame: number, set?: boolean): void;
     snowball(x: number, y: number): void;
-    joinRoom(room: number, x?: number, y?: number): Promise<ServerMessages["join_room"]>;
-    addItem(item: number): Promise<ServerMessages["add_item"]>;
+    joinRoom(room: number, x?: number, y?: number, options?: ClientOperationOptions): Promise<ServerMessages["join_room"]>;
+    addItem(item: number, options?: ClientOperationOptions): Promise<ServerMessages["add_item"]>;
     equipColor(item: number): void;
     equipHead(item: number): void;
     equipFace(item: number): void;
@@ -1027,32 +1348,59 @@ declare class Client extends EventEmitter {
     equipFlag(item: number): void;
     equipPhoto(item: number): void;
     buddyRequest(id: number): void;
-    buddyAccept(id: number): Promise<ServerMessages["buddy_accept"]>;
-    buddyReject(id: number): Promise<ServerMessages["buddy_reject"]>;
-    buddyRequestSeen(id: number): Promise<ServerMessages["buddy_request_seen"]>;
-    getBuddy(id: number, type: "buddies" | "buddyRequests"): Promise<ServerMessages["get_buddy"]>;
+    buddyAccept(id: number, options?: ClientOperationOptions): Promise<ServerMessages["buddy_accept"]>;
+    buddyReject(id: number, options?: ClientOperationOptions): Promise<ServerMessages["buddy_reject"]>;
+    buddyRequestSeen(id: number, options?: ClientOperationOptions): Promise<ServerMessages["buddy_request_seen"]>;
+    getBuddy(id: number, type: "buddies" | "buddyRequests", options?: ClientOperationOptions): Promise<ServerMessages["get_buddy"]>;
+    findBuddy(id: number, options?: ClientOperationOptions): Promise<ServerMessages["buddy_find"]>;
     removeBuddy(id: number): void;
-    addIgnore(id: number): Promise<ServerMessages["ignore_add"]>;
-    removeIgnore(id: number): Promise<ServerMessages["ignore_remove"]>;
-    getPlayer(id: number): Promise<ServerMessages["get_player"]>;
-    getAllSlots(): Promise<ServerMessages["slot"]>;
-    getMascots(): Promise<ServerMessages["get_mascots"]>;
-    sendPostcard(userId: number, cardId: string): Promise<ServerMessages["send_postcard"]>;
-    getStamps(userId: number): Promise<ServerMessages["stamps_result"]>;
-    getPostcards(): Promise<ServerMessages["get_postcards"]>;
-    getIglooOpen(igloo: number): Promise<ServerMessages["get_igloo_open"]>;
-    getIgloos(): Promise<ServerMessages["get_igloos"]>;
-    getPuffles(userId: number): Promise<ServerMessages["get_puffles"]>;
-    adoptPuffle(type: number, name: string): Promise<ServerMessages["adopt_puffle"]>;
-    getIglooLikes(): Promise<ServerMessages["get_igloo_likes"]>;
+    addIgnore(id: number, options?: ClientOperationOptions): Promise<ServerMessages["ignore_add"]>;
+    removeIgnore(id: number, options?: ClientOperationOptions): Promise<ServerMessages["ignore_remove"]>;
+    getPlayer(id: number, options?: ClientOperationOptions): Promise<ServerMessages["get_player"]>;
+    getAllSlots(options?: ClientOperationOptions): Promise<ServerMessages["slot"]>;
+    getMascots(options?: ClientOperationOptions): Promise<ServerMessages["get_mascots"]>;
+    sendPostcard(userId: number, cardId: string, options?: ClientOperationOptions): Promise<ServerMessages["send_postcard"]>;
+    getStamps(userId: number, options?: ClientOperationOptions): Promise<ServerMessages["stamps_result"]>;
+    getPostcards(options?: ClientOperationOptions): Promise<ServerMessages["get_postcards"]>;
+    getIglooOpen(igloo: number, options?: ClientOperationOptions): Promise<ServerMessages["get_igloo_open"]>;
+    getIgloos(options?: ClientOperationOptions): Promise<ServerMessages["get_igloos"]>;
+    getPuffles(userId: number, options?: ClientOperationOptions & {
+        isBackyard?: boolean;
+    }): Promise<ServerMessages["get_puffles"]>;
+    getAllPuffles(options?: ClientOperationOptions): Promise<ServerMessages["get_all_puffles"]>;
+    getPuffleWellbeing(puffle: number, options?: ClientOperationOptions): Promise<ServerMessages["get_wellbeing"]>;
+    playPuffle(puffle: number): void;
+    restPuffle(puffle: number): void;
+    buyPuffleItem(puffleId: number, item: number, options?: ClientOperationOptions): Promise<ServerMessages["buy_puffle_item"]>;
+    walkPuffle(puffle: number, options?: ClientOperationOptions): Promise<ServerMessages["get_walking_puffle"]>;
+    /** CPJourney sends tower_init after its walking-puffle acknowledgement. */
+    initializePuffleTower(): void;
+    getBackyardSupplies(options?: ClientOperationOptions): Promise<ServerMessages["backyard_supplies"]>;
+    adoptPuffle(type: number, name: string, options?: ClientOperationOptions): Promise<ServerMessages["adopt_puffle"]>;
+    getIglooLikes(options?: ClientOperationOptions): Promise<ServerMessages["get_igloo_likes"]>;
     checkPuffleSprite(puffleSprite: boolean): void;
-    joinIgloo(igloo: number, x?: number, y?: number): Promise<ServerMessages["join_igloo"]>;
-    gameOver(coins: number): Promise<ServerMessages["game_over"]>;
-    collectStamp(stamp: number): Promise<ServerMessages["stamp_earned"]>;
+    joinIgloo(igloo: number, x?: number, y?: number, options?: ClientOperationOptions): Promise<ServerMessages["join_igloo"]>;
+    getStoreMusic(options?: ClientOperationOptions): Promise<ServerMessages["get_store_music"]>;
+    buyMusic(music: string, options?: ClientOperationOptions): Promise<ServerMessages["add_music"]>;
+    getIglooStoreItems(options?: ClientOperationOptions): Promise<ServerMessages["get_igloostore_items"]>;
+    buyFurniture(furniture: string, amount?: number, options?: ClientOperationOptions): Promise<ServerMessages["add_furniture"]>;
+    updateIglooMusic(music: string, options?: ClientOperationOptions): Promise<ServerMessages["update_music"]>;
+    updateIglooFurniture(furniture: ClientMessages["update_furniture"]["furniture"]): void;
+    autoUpdateIglooFurniture(furniture: ClientMessages["update_furniture_auto"]["furniture"]): void;
+    updateIglooType(type: number): void;
+    openIgloo(options?: ClientOperationOptions): Promise<ServerMessages["igloo_open_status"]>;
+    closeIglooBounds(options?: ClientOperationOptions): Promise<ServerMessages["igloo_bounds_status"]>;
+    likeIgloo(options?: ClientOperationOptions): Promise<ServerMessages["igloo_liked"]>;
+    openIglooEditor(): void;
+    closeIglooEditor(): void;
+    gameOver(coins: number, options?: ClientOperationOptions): Promise<ServerMessages["game_over"]>;
+    collectStamp(stamp: number, options?: ClientOperationOptions): Promise<ServerMessages["stamp_earned"]>;
     sleep(ms: number): Promise<void>;
     disconnect(): void;
+    private reportLifecycle;
+    private handleAdapterDisconnect;
     private cleanup;
     private handleMessage;
 }
 
-export { type AdapterName, BaseAdapter, type Buddy, CardJitsu, Client, type ClientMessages, type ClientOptions, type ConnectOptions, type ConnectionProfile, type ConnectionProfileInput, type ConnectionProfilePreset, type GameCard, type GamePlayer, type LogFn, type LoginOptions, type LoginResult, type Mascot, type MatState, type NinjaCard, type NinjaData, type NinjaProgress, type PlayerAppearance, type PlayerData, type PlayerSettings, type Postcard, type QueueUpdate, type RevealedCard, type RoomUser, type RoundResult, type ServerInfo, type ServerMessages, type TokenLoginOptions };
+export { type AdapterName, BaseAdapter, type Buddy, CardJitsu, Client, type ClientConnectionTimeouts, type ClientDisconnectInfo, type ClientLifecyclePhase, type ClientLifecycleUpdate, type ClientMessages, ClientOperationError, type ClientOperationErrorCategory, type ClientOperationErrorOptions, type ClientOperationOptions, type ClientOptions, type ConnectOptions, type ConnectionProfile, type ConnectionProfileInput, type ConnectionProfilePreset, type CpjourneyClientMessages, type CpjourneyServerMessages, DEFAULT_CLIENT_CONNECTION_TIMEOUTS, type FurnitureStoreItem, type GameCard, type GamePlayer, type IglooFurniturePlacement, type IglooStoreItem, type LogFn, type LoginOptions, type LoginResult, type Mascot, type MatState, type NinjaCard, type NinjaData, type NinjaProgress, type PlayerAppearance, type PlayerData, type PlayerSettings, type Postcard, type Puffle, type PuffleWellbeing, type QueueUpdate, type RevealedCard, type RoomUser, type RoundResult, type ServerInfo, type ServerMessages, type TokenLoginOptions, sanitizeClientErrorMessage };