dredless 0.7.0 → 1.0.1

package/src/index.d.ts

@@ -1,3 +1,12 @@
+export const GravityDirection: {
+    readonly Down: "down";
+    readonly Up: "up";
+    readonly Left: "left";
+    readonly Right: "right";
+};
+export type GravityDirection = typeof GravityDirection[keyof typeof GravityDirection];
+export type ShipGravityDirection = GravityDirection | 0 | 1 | 2 | 3;
+
 export interface Server {
     index: number;
     domain: string;
@@ -26,15 +35,12 @@ export interface ShipList {
 export interface InviteMetadata {
     shipId: string | null;
     name: string | null;
-    /** CSS RGB color sampled from the preview image's top-left pixel, when available. */
-    color?: string | null;
     previewImageUrl: string | null;
     hostname: string;
     inviteCode: string;
 }
 export interface InviteFetchOptions {
     fetchImpl?: typeof fetch;
-    includeColor?: boolean;
 }
 export function fetchInviteMetadata(invite: string | URL, options?: InviteFetchOptions): Promise<InviteMetadata>;
 export function parseInviteMetadata(html: string): InviteMetadata;
@@ -54,6 +60,73 @@ export type ServerRef = number | Server;
 export type ShipRef = number | string | Ship | ShipSpec | null;
 export type ShipPrivacy = 0 | 1 | boolean | "public" | "private";
 export type ShipPlayerRank = 0 | 1 | 3 | "guest" | "crew" | "captain";
+
+export const DropReason: Readonly<{
+    ProtocolError: 4000;
+    BadVersion: 4001;
+    ConnectLimit: 4002;
+    ConnectRate: 4003;
+    TeamLimit: 4004;
+    FullPlayers: 4005;
+    FullTeams: 4006;
+    TeamNotAvailable: 4007;
+    Kicked: 4008;
+    Banned: 4009;
+    Idle: 4010;
+    ShipDestruct: 4011;
+    JoinBlocked: 4012;
+    HardBanned: 4013;
+    NoLoad: 4014;
+    Saved: 4015;
+    InvalidInvite: 4016;
+    Shutdown: 4017;
+    ServerError: 4018;
+    GTFO: 4019;
+}>;
+export type DropReason = typeof DropReason[keyof typeof DropReason];
+
+export interface DisconnectInfo {
+    readonly code: number;
+    /** Official application reason name; null for standard WebSocket or unknown codes. */
+    readonly name: keyof typeof DropReason | null;
+    readonly reason: string;
+    /** Null when the socket API does not report handshake cleanliness. */
+    readonly wasClean: boolean | null;
+}
+
+export class DisconnectError extends Error {
+    constructor(disconnect: DisconnectInfo, message?: string);
+    disconnect: DisconnectInfo;
+}
+
+export function normalizeDisconnect(eventOrCode?: unknown, reason?: unknown): DisconnectInfo;
+
+export interface ShipManagementOptions {
+    /** Milliseconds to wait for server confirmation; default 10000. */
+    timeout?: number;
+}
+
+export interface StarterRecoveryOptions {
+    /** Milliseconds to wait for the response; default 10000. */
+    timeout?: number;
+}
+
+export interface StarterRecoveryResult {
+    readonly success: boolean;
+    readonly failReason: string | null;
+}
+
+export interface RenameShipOptions {
+    /** #RRGGBB hex string; omitted preserves the color returned by the server. */
+    color?: string;
+    /** Milliseconds to wait for rename permission; default 10000. */
+    timeout?: number;
+}
+
+export interface SaveShipOptions {
+    /** Milliseconds to wait for the Saved disconnect code; default 10000. */
+    timeout?: number;
+}
 export type PlayerShipRank = "guest" | "crew" | "crew-invite-pending-deprecated" | "captain" | "banned";
 export const FabricatorType: {
     readonly Starter: "starter";
@@ -82,12 +155,24 @@ export type InventorySlotRef = number | EquipmentSlot | InventorySlotHandle | In
 export type ReadWorldScope = "ship" | "current" | "overworld" | number;
 export type EntityRef = number | EntityHandle | EntitySummary | EntityDebugSummary;
 
+export interface ShipPatronPerk {
+    name: string;
+    /** Packed RGB color, as sent by the server. */
+    color: number;
+    /** Official tiers include bronze, silver, gold, plat, and flux. */
+    tier: string;
+}
+
+export interface PatronPerksResponse {
+    readonly failure: boolean;
+}
+
 export interface ShipConfig {
     privacy: number | null;
     privacyName: "public" | "private" | null;
     inviteKey: string | null;
     teamId: number | null;
-    patronPerks: unknown[];
+    patronPerks: ShipPatronPerk[];
 }
 
 export interface CaptainSubrank {
@@ -196,10 +281,30 @@ export interface Command {
     drag?: DragPayload | null;
 }
 
+export interface CrewLogEntry {
+    icon: string | null;
+    /** Plain text; formatting, images, badges, and date tokens remain in rawText. */
+    text: string;
+    rawText: unknown;
+    count: number;
+    refId: number | null;
+    secondaryRefId: number | null;
+}
+
+export interface CrewLog {
+    /** Retained entries in server order, oldest first; at most 500. */
+    entries: CrewLogEntry[];
+    /** Entries appended by the latest message, including amended replacements. */
+    changes: CrewLogEntry[];
+    reset: boolean;
+    amend: boolean;
+}
+
 export interface ShipManagementMessage {
     type: 4;
     act: string;
     arg: unknown;
+    arg2?: unknown;
     rank?: unknown;
 }
 
@@ -324,6 +429,34 @@ export interface LoaderFullConfig extends LoaderConfig {
     filterSlots?: Array<number | null | undefined>;
 }
 
+export interface ClanTagDetails {
+    /** Current tag, or null when cleared. */
+    tag: string | null;
+    /** Number of other users with this tag; null when unavailable. */
+    otherUsers: number | null;
+}
+
+export interface AccountPerkShip {
+    /** Decimal identifier from the removal form; use this for removeShipPerks(). */
+    shipId: string;
+    name: string;
+    /** Identifier displayed in braces; distinct from the removal form's ID. */
+    hexCode: string | null;
+}
+
+export interface AccountDetails {
+    name: string | null;
+    /** Packed RGB account color from the name's background, matching account/status. */
+    color: number | null;
+    email: string | null;
+    /** Identity value without the parenthesized service suffix. */
+    identity: string | null;
+    identityService: string | null;
+    clan: ClanTagDetails;
+    /** This account's applied ships; null when the section is unavailable. */
+    shipsWithPerks: AccountPerkShip[] | null;
+}
+
 export class Session {
     constructor(gameSession?: string | null, gameVersion?: string | null);
 
@@ -349,6 +482,16 @@ export class Session {
 
     fetchAccountStatus(): Promise<unknown>;
 
+    /** Scrape the authenticated account page; does not update account/status or session serialization. */
+    fetchAccountDetails(): Promise<AccountDetails>;
+    fetchClanTag(): Promise<ClanTagDetails>;
+    /** Submit the form and confirm the stored tag on the account page. */
+    setClanTag(tag: string): Promise<ClanTagDetails>;
+    clearClanTag(): Promise<ClanTagDetails>;
+    /** Remove this account's perks and return the confirmed remaining applied ships. */
+    removeShipPerks(shipId: string | number): Promise<AccountPerkShip[]>;
+
+
     fetchShips(server: ServerRef): Promise<Ship[]>;
 
     fetchShipList(server: ServerRef): Promise<ShipList>;
@@ -475,6 +618,8 @@ export class DredlessClient {
     ready: boolean;
     packetCount: number;
     lastPacket: unknown;
+    lastDisconnect: DisconnectInfo | null;
+    crewLog: CrewLog | null;
     net: ClientNetDomain;
     debug: ClientDebugDomain;
     player: PlayerDomain;
@@ -490,6 +635,19 @@ export class DredlessClient {
     disconnect(code?: number, reason?: string): this;
     sendChatMessage(message?: string): this;
     sendCommsMessage(message?: string): this;
+    /** Whether the connected, ready client's ship has parent-world danger level 0. */
+    canSaveShip(): boolean;
+    /** Save and await the server's Saved close code; reject on ineligibility, timeout, or any other disconnect. */
+    saveShip(options?: SaveShipOptions): Promise<DisconnectInfo>;
+    /** Request permission and send the rename commit; does not await confirmation of the new name. */
+    renameShip(name: string, options?: RenameShipOptions): Promise<void>;
+    unbanPlayer(refId: number): this;
+    setShipGravity(direction: ShipGravityDirection): this;
+    setShipPatronPerks(enabled: boolean): this;
+    resetInvite(options?: ShipManagementOptions): Promise<ShipConfig>;
+    demoteSelf(options?: ShipManagementOptions): Promise<void>;
+    /** Await recovery success; reject with the server's failure reason. */
+    recoverStarterItem(itemId: number, options?: StarterRecoveryOptions): Promise<void>;
 
     currentShip(): ShipDomain | null;
 
@@ -513,12 +671,27 @@ export class DredlessClient {
 
     entity(entityId: number, scope?: number | string): EntitySnapshot | null;
 
+    on(type: "disconnect", callback: (info: DisconnectInfo) => void): this;
+    on(type: "starter-recovery", callback: (result: StarterRecoveryResult, packet: unknown) => void): this;
+    on(type: "demote", callback: (packet: unknown) => void): this;
+    on(type: "patron-perks-response", callback: (response: PatronPerksResponse, packet: unknown) => void): this;
+    on(type: "crew-log", callback: (log: CrewLog | null, packet: unknown) => void): this;
     on(type: "tip-list", callback: (menu: TipList, world: WorldState) => void): this;
     on(type: string, callback: (...args: unknown[]) => void): this;
 
+    off(type: "disconnect", callback: (info: DisconnectInfo) => void): this;
+    off(type: "starter-recovery", callback: (result: StarterRecoveryResult, packet: unknown) => void): this;
+    off(type: "demote", callback: (packet: unknown) => void): this;
+    off(type: "patron-perks-response", callback: (response: PatronPerksResponse, packet: unknown) => void): this;
+    off(type: "crew-log", callback: (log: CrewLog | null, packet: unknown) => void): this;
     off(type: "tip-list", callback: (menu: TipList, world: WorldState) => void): this;
     off(type: string, callback: (...args: unknown[]) => void): this;
 
+    once(type: "disconnect", callback: (info: DisconnectInfo) => void): this;
+    once(type: "starter-recovery", callback: (result: StarterRecoveryResult, packet: unknown) => void): this;
+    once(type: "demote", callback: (packet: unknown) => void): this;
+    once(type: "patron-perks-response", callback: (response: PatronPerksResponse, packet: unknown) => void): this;
+    once(type: "crew-log", callback: (log: CrewLog | null, packet: unknown) => void): this;
     once(type: "tip-list", callback: (menu: TipList, world: WorldState) => void): this;
     once(type: string, callback: (...args: unknown[]) => void): this;
 }
@@ -554,6 +727,7 @@ export interface ClientNetDomain {
     sid: number | null;
     packetCount: number;
     lastPacket: unknown;
+    readonly lastDisconnect: DisconnectInfo | null;
 
     send(command?: Command): DredlessClient;
 
@@ -636,13 +810,36 @@ export interface PlayerDomain {
 }
 
 export interface ShipManagementDomain {
+    /** Checks the current ship's parent-world danger level; server permissions still apply. */
+    canSave(): boolean;
+
+    /** Save and await the server's Saved close code; reject on ineligibility, timeout, or any other disconnect. */
+    save(options?: SaveShipOptions): Promise<DisconnectInfo>;
+
+    /** Request permission and send the rename commit; does not await confirmation of the new name. */
+    rename(name: string, options?: RenameShipOptions): Promise<void>;
+
     requestPlayerList(): DredlessClient;
 
-    resetInvite(): DredlessClient;
+    /** Await a server config containing a changed, nonempty invite key. */
+    resetInvite(options?: ShipManagementOptions): Promise<ShipConfig>;
 
     setPrivacy(privacy: ShipPrivacy): DredlessClient;
 
-    recoverStarterItem(itemId: number): DredlessClient;
+    /** Set gravity using the official coolsnake303 command. Does not await confirmation. */
+    setGravity(direction: ShipGravityDirection): DredlessClient;
+
+    /** Apply or remove the caller's perks; does not await server confirmation. */
+    setPatronPerks(enabled: boolean): DredlessClient;
+    enablePatronPerks(): DredlessClient;
+    disablePatronPerks(): DredlessClient;
+    /** Current server-reported patrons; null when config is unavailable. */
+    patronPerks(): ShipPatronPerk[] | null;
+    /** Any applied patron, or an exact patron name match when supplied. */
+    hasPatronPerks(name?: string): boolean;
+
+    /** Await recovery success; reject with the server's failure reason. */
+    recoverStarterItem(itemId: number, options?: StarterRecoveryOptions): Promise<void>;
 
     setPlayerRank(refId: number, rank: ShipPlayerRank): DredlessClient;
 
@@ -650,13 +847,19 @@ export interface ShipManagementDomain {
 
     banPlayer(refId: number): DredlessClient;
 
-    demoteSelf(): DredlessClient;
+    /** Remove a ship ban using the player list entry’s refId. */
+    unbanPlayer(refId: number): DredlessClient;
+
+    /** Await server demotion; management caches have been cleared when this resolves. */
+    demoteSelf(options?: ShipManagementOptions): Promise<void>;
 
     config(): ShipConfig | null;
 
     hasCheats(): boolean;
 
     playerList(): ShipPlayerList | null;
+
+    crewLog(): CrewLog | null;
 }
 
 export interface InventoryDomain {
@@ -1228,6 +1431,7 @@ export interface ClientSnapshot {
     sid: number | null;
     ready: boolean;
     connected: boolean;
+    lastDisconnect: DisconnectInfo | null;
     currentWorldId: number | null;
     worlds: WorldSnapshot[];
     cpuLoad: number | null;
@@ -1245,6 +1449,7 @@ export interface ClientSnapshot {
     shipConfig: ShipConfig | null;
     captainSubrank: CaptainSubrank | null;
     playerList: ShipPlayerList | null;
+    crewLog: CrewLog | null;
     outfits: { sid: number; outfit: unknown }[];
     commandAcks: CommandAck[];
     lastCommandAck: CommandAck | null;
@@ -1638,6 +1843,9 @@ export interface CommsBubbleSummary {
 }
 
 export class ModelState {
+    /** Local entity identified by the decrypted camera-focus message, when known. */
+    readonly localPlayerEntity: number | null;
+    setLocalPlayerEntity(entity: number | null): void;
     generation: number | null;
     tables: Map<number, Map<number, ModelRecord>>;
     /** Capped at 500 retained ids; see `totalRemovedCount` for the true total. */
@@ -1839,10 +2047,17 @@ export interface CannonSummary {
     recoil: number | null;
     recoil2: number | null;
     recoils: [number | null, number | null];
-    charge: number | null;
-    charged: boolean | null;
+    /** Official indicator scalar (wire value / 50); defaults to 0. Not a resource count or readiness flag. */
+    indicatorValue: number;
+    indicatorVisible: boolean;
+    /** Packed RGB; null when hidden. Red is the first phase of a blinking indicator. */
+    indicatorColor: number | null;
+    indicatorBlinking: boolean;
+    /** Alternate packed RGB color for blinking; otherwise null. */
+    indicatorBlinkColor: number | null;
     spin: number | null;
-    coolingCellCount: number;
+    /** Burst charges on burst cannons, cooling cells on machine cannons; defaults to 0. */
+    resourceCount: number;
     state: ModelRecord;
 }
 
@@ -2037,18 +2252,73 @@ export interface PlayerSummary {
     name: string | null;
     heldItemId: number | null;
     heldItemName: string | null;
-    repairTargetDistance: number | null;
-    repairTargetAngle: number | null;
+    /** Server-reported item mode code. */
+    itemMode: number | null;
+    /** Multiplier used by the official client for build reach. */
+    buildMultiplier: number | null;
+    /** Beam distance shared by repair tools and handheld pushers, in world units. */
+    heldItemBeamDistance: number | null;
+    /** Held tool angle in radians in the current world's coordinate frame. */
+    heldItemAngle: number | null;
     shipRank: PlayerShipRank | null;
     patronTier: "bronze" | "silver" | "gold" | "plat" | "flux" | null;
     isDeveloper: boolean;
     isPatron: boolean;
-    piloting: boolean;
+    isLocal: boolean;
+    /** Server-requested camera zoom state; does not identify the operated machine. */
+    zoomedOut: boolean;
     muted: boolean;
+    invisible: boolean;
+    cheats: { noclip: boolean; sandboxBuild: boolean };
+    /** Shared item effect flag, including active rocket/hover pack exhaust. */
+    itemEffectActive: boolean;
+    animation: PlayerAnimationSummary;
+    appearance: PlayerAppearanceSummary | null;
     actionPreview: PlayerActionPreviewSummary | null;
     state: ModelRecord;
 }
 
+export interface PlayerAnimationSummary {
+    /** Horizontal sprite mirror sign, normally -1 or 1. */
+    facing: number;
+    /** Server orientation code used to align the sprite and limb animation. */
+    orientation: number;
+    /** Selects speed-based limb swing instead of the hovering pose; not a movement detector. */
+    walking: boolean;
+}
+
+export interface PlayerAppearanceStyleSummary {
+    color: number;
+    /** Index into the official client's style catalog; zero means no style. */
+    styleId: number;
+}
+
+export interface PlayerAppearanceItemSummary {
+    itemId: number;
+    itemName: string | null;
+}
+
+export interface PlayerAppearanceSummary {
+    /** Packed RGB colors. */
+    bodyColor: number;
+    legsColor: number;
+    skinColor: number;
+    feetColor: number;
+    hair: PlayerAppearanceStyleSummary;
+    hat: PlayerAppearanceStyleSummary;
+    face1: PlayerAppearanceStyleSummary;
+    face2: PlayerAppearanceStyleSummary;
+    /** Equipped item visuals applied over the base outfit; null means no item override. */
+    itemOverrides: {
+        back: PlayerAppearanceItemSummary | null;
+        hands: PlayerAppearanceItemSummary | null;
+        feet: PlayerAppearanceItemSummary | null;
+        head1: PlayerAppearanceItemSummary | null;
+        head2: PlayerAppearanceItemSummary | null;
+    };
+    state: ModelRecord;
+}
+
 export interface PlayerActionPreviewSummary {
     entity: number;
     active: boolean;
@@ -2194,10 +2464,22 @@ export function buildShipManagementMessage(act: string, arg?: unknown, extra?: R
 
 export function buildShipPrivacyMessage(privacy: ShipPrivacy): ShipManagementMessage;
 
+export function buildShipGravityMessage(direction: ShipGravityDirection): ShipManagementMessage;
+
+export function buildSetPatronPerksMessage(enabled: boolean): ShipManagementMessage;
+
+export function normalizeGravityDirection(direction: ShipGravityDirection): 0 | 1 | 2 | 3;
+
 export function buildStarterRecoveryMessage(itemId: number): ShipManagementMessage;
 
 export function buildPlayerListMessage(): ShipManagementMessage;
 
+export function buildSaveShipMessage(): ShipManagementMessage;
+
+export function buildShipRenameRequestMessage(): ShipManagementMessage;
+
+export function buildShipRenameCommitMessage(name: string, color: string): ShipManagementMessage;
+
 export function buildInviteResetMessage(): ShipManagementMessage;
 
 export function buildSetPlayerRankMessage(refId: number, rank: ShipPlayerRank): ShipManagementMessage;
@@ -2206,6 +2488,8 @@ export function buildKickPlayerMessage(refId: number): ShipManagementMessage;
 
 export function buildBanPlayerMessage(refId: number): ShipManagementMessage;
 
+export function buildUnbanPlayerMessage(refId: number): ShipManagementMessage;
+
 export function buildDemoteSelfMessage(): ShipManagementMessage;
 
 export function normalizePrivacy(privacy: ShipPrivacy): 0 | 1;
@@ -2216,6 +2500,8 @@ export function normalizeShipConfig(event: unknown): ShipConfig;
 
 export function normalizeCaptainSubrank(event: unknown): CaptainSubrank;
 
+export function normalizeCrewLog(event: unknown, previous?: CrewLog | null): CrewLog;
+
 export function normalizeShipPlayerList(event: unknown, previous?: ShipPlayerList | null, currentCaptainSubrank?: CaptainSubrank | null): ShipPlayerList;
 
 export function buildSignTextMessage(text?: string, mode?: SignDisplayMode): SignTextMessage;

package/src/index.js

@@ -1,5 +1,6 @@
 export {Session, AnonSession} from "./network/session.js";
 export {Connection} from "./network/connection.js";
+export {DropReason, DisconnectError, normalizeDisconnect} from "./network/disconnect.js";
 export {DredlessClient, WrenchMode, TurretMode} from "./client/index.js";
 export {WorldStore, WorldState} from "./state/world/index.js";
 export {FabricatorType, ModelState, decodeModelData} from "./state/model/index.js";
@@ -24,15 +25,24 @@ export {
 } from "./protocol/outbound/inventory.js";
 export {
     buildBanPlayerMessage,
+    buildUnbanPlayerMessage,
     buildDemoteSelfMessage,
     buildInviteResetMessage,
     buildKickPlayerMessage,
     buildPlayerListMessage,
+    buildSaveShipMessage,
+    buildShipRenameRequestMessage,
+    buildShipRenameCommitMessage,
     buildShipManagementMessage,
     buildSetPlayerRankMessage,
     buildShipPrivacyMessage,
+    buildShipGravityMessage,
+    buildSetPatronPerksMessage,
+    GravityDirection,
+    normalizeGravityDirection,
     buildStarterRecoveryMessage,
     normalizeCaptainSubrank,
+    normalizeCrewLog,
     normalizeShipPlayerList,
     normalizePlayerRank,
     normalizePrivacy,