dredless 0.7.0 → 1.0.1

package/docs/NODE_API.md

@@ -1,393 +1,195 @@
-# Dredless Node API
+# Node sessions and connections
 
-This document covers the Node-specific top-level API: explicit sessions, anonymous token/session creation, connection descriptors, and convenience start/join helpers.
+[Documentation index](README.md) · [Getting started](GETTING_STARTED.md) · [API reference](API_REFERENCE.md)
 
-Use this entrypoint when you want the multi-session cookie-jar API:
+## Contents
 
-```js
-import Dredless, {
-  Session,
-  AnonSession,
-  Connection,
-  DredlessClient
-} from "dredless/node";
-```
+- [Imports and sessions](#imports-and-sessions)
+- [Authentication and reuse](#authentication-and-reuse)
+- [Servers and ship lists](#servers-and-ship-lists)
+- [Join, start, and invites](#join-start-and-invites)
+- [Construct a client yourself](#construct-a-client-yourself)
+- [HTTP requests](#http-requests)
+- [Serialization](#serialization)
 
-Normal Node usage:
+## Imports and sessions
 
 ```js
-const session = await Dredless.createAnonSession();
-const servers = await Dredless.fetchServers();
-const ships = await session.fetchShips(servers[0]);
-const client = await session.startShip(servers[0], ships[0]);
-
-await client.whenReady();
-```
-
-Shared input shapes such as `Server`, `ServerRef`, `Ship`, `ShipRef`, and `ShipSpec` are documented in [API_REFERENCE.md](./API_REFERENCE.md#common-input-types). Shared client/world/entity/domain APIs are also documented in [API_REFERENCE.md](./API_REFERENCE.md).
-
-## `Dredless` Namespace
-
-The default export is a namespace of constructors and convenience factories.
-
-```ts
-interface DredlessNamespace {
-  Session: typeof Session;
-  AnonSession: typeof AnonSession;
-  Connection: typeof Connection;
-  DredlessClient: typeof DredlessClient;
-  createSession: typeof createSession;
-  createAnonSession: typeof createAnonSession;
-  createAnonToken: typeof createAnonToken;
-  fetchNoticeVersion: typeof fetchNoticeVersion;
-  fetchGameVersion: typeof fetchGameVersion;
-  fetchServers: typeof fetchServers;
-  fetchShips: typeof fetchShips;
-  fetchShipList: typeof fetchShipList;
-  fetchInviteMetadata: typeof fetchInviteMetadata;
-  joinShip: typeof joinShip;
-  startShip: typeof startShip;
-  startNewShip: typeof startNewShip;
-  joinInvite: typeof joinInvite;
-}
+import Dredless, {Session, AnonSession, Connection, DredlessClient} from "dredless/node";
 ```
 
-### `Dredless.createSession(noticeVersion?)`
+The default `Dredless` export contains constructors and the HTTP/start/join convenience functions below. Protocol builders and constants are named exports; they are not all properties of the default namespace.
 
-```ts
-function createSession(noticeVersion?: number | null): Promise<Session>;
-```
-
-Creates a `Session` using the current game version lookup and optional notice
-version. It does not create an anonymous account.
-
-### `Dredless.createAnonSession(anonKey?, noticeVersion?, baseUrl?)`
+A `Session` owns an HTTP cookie jar. It does not open a WebSocket until you call a client factory. `AnonSession` adds an `anonKey`. Reuse one session for actions that should use the same identity; use separate sessions for separate identities.
 
 ```ts
-function createAnonSession(
-  anonKey?: string | null,
-  noticeVersion?: number | null,
-  baseUrl?: string
-): Promise<AnonSession>;
-```
+new Session(gameSession?: string | null, gameVersion?: string | null): Session;
+new AnonSession(gameSession?: string | null, anonKey?: string | null,
+                gameVersion?: string | null): AnonSession;
 
-Creates an anonymous session. If `anonKey` is omitted, the library requests one
-from the server.
+Dredless.createSession(noticeVersion?: number | null): Promise<Session>;
+Dredless.createAnonSession(anonKey?: string | null, noticeVersion?: number | null,
+                           baseUrl?: string): Promise<AnonSession>;
+Dredless.createAnonToken(noticeVersion?: number | null, baseUrl?: string): Promise<string>;
 
-Returns an `AnonSession`.
-
-### `Dredless.createAnonToken(noticeVersion?, baseUrl?)`
-
-```ts
-function createAnonToken(
-  noticeVersion?: number | null,
-  baseUrl?: string
-): Promise<string>;
+session.fetchAccountStatus(): Promise<unknown>;
 ```
 
-Requests a new anonymous account token.
+Constructors perform no I/O. `createSession()` fetches account status into a fresh session; it does not log in to a registered account. `createAnonToken()` requests a new anonymous key. `createAnonSession()` uses the supplied key, or requests one when omitted, then fetches status.
 
-### `Dredless.fetchNoticeVersion()`
+`noticeVersion` is optional; factories attempt to discover it and have a built-in fallback. Alternate `baseUrl` values are origins such as `https://test.drednot.io`. The implementation also accepts `baseUrl` as the third `Session` constructor argument, fourth `AnonSession` argument, and second `createSession()` argument; these overloads are not currently represented in the root declarations.
 
-```ts
-function fetchNoticeVersion(): Promise<number>;
-```
+## Authentication and reuse
 
-Scrapes the current notice version needed by anon login.
+### Existing anonymous identity
 
-### `Dredless.fetchGameVersion()`
+```js
+import Dredless from "dredless/node";
 
-```ts
-function fetchGameVersion(): Promise<string>;
+const key = process.env.DREDNOT_ANON_KEY;
+if (!key) throw new Error("Set DREDNOT_ANON_KEY to reuse an existing anonymous account");
+const session = await Dredless.createAnonSession(key);
 ```
 
-Scrapes the current game version string from the site.
+For a new anonymous account, call `createAnonSession()` once and retain `session.anonKey` in your own credential storage. Recreating a session without supplying the key creates a different identity.
 
-### `Dredless.fetchServers()`
+### Existing registered session
 
-```ts
-function fetchServers(): Promise<Server[]>;
-```
+Supply your own authenticated `game_session` cookie value. Dredless does not implement the website's identity-provider login flow:
 
-Scrapes and returns game servers.
-### `Dredless.fetchServerStatus(server)`
+```js
+import {Session} from "dredless/node";
 
-```ts
-function fetchServerStatus(server: ServerRef): Promise<{ playerCount: number; maxPlayerCount: number; ping: number }>;
+const cookie = process.env.DREDNOT_GAME_SESSION;
+if (!cookie) throw new Error("Set DREDNOT_GAME_SESSION");
+const session = new Session(cookie);
+await session.fetchAccountStatus();
+if (!session.account?.is_registered) throw new Error("The session is not a registered account");
 ```
 
-Pings the server and returns the current player counts and measured response time in milliseconds.
-
-### `Dredless.fetchServerStatuses()`
-
-```ts
-function fetchServerStatuses(): Promise<Server[]>;
-```
+`session.account` is the normalized cached status: `{name, color, game_rank, user_badges, is_registered}` or `null`. `color` is packed RGB. `fetchAccountStatus()` returns the full decoded JSON and updates this cache, along with `geoServer`, `isRegistered`, `upgraded`, `showAds`, `forceTutorial`, and `ban`.
 
-Fetches status for every server and returns server objects with updated `playerCount`, `maxPlayerCount`, and `ping` fields.
+Email, identity service, clan tags, and applied perk ships use [account-page methods](ACCOUNT.md), not `account/status`.
 
-### `Dredless.fetchShips(session, server)`
+## Servers and ship lists
 
 ```ts
-function fetchShips(session: Session, server: ServerRef): Promise<Ship[]>;
-```
-
-Authenticated convenience wrapper around `session.fetchShips(server)`.
-
-Ship names in the returned objects are canonical Drednot server data. Leading
-and trailing spaces are preserved exactly; callers should not trim them.
+Dredless.fetchServers(): Promise<Server[]>;
+Dredless.fetchServerStatus(server: ServerRef): Promise<ServerStatus>;
+Dredless.fetchServerStatuses(): Promise<(Server & ServerStatus)[]>;
+Dredless.fetchGameVersion(): Promise<string>;
+Dredless.fetchNoticeVersion(): Promise<number>;
 
-### `Dredless.fetchShipList(session, server)`
+session.fetchShips(server: ServerRef): Promise<Ship[]>;
+session.fetchShipList(server: ServerRef): Promise<ShipList>;
 
-```ts
-function fetchShipList(session: Session, server: ServerRef): Promise<ShipList>;
+Dredless.fetchShips(session: Session, server: ServerRef): Promise<Ship[]>;
+Dredless.fetchShipList(session: Session, server: ServerRef): Promise<ShipList>;
 ```
 
-Authenticated convenience wrapper around `session.fetchShipList(server)`.
+| Type           | Meaning                                                                                           |
+|----------------|---------------------------------------------------------------------------------------------------|
+| `Server`       | `{index, domain, description}`                                                                    |
+| `ServerRef`    | A `Server` object or its numeric `index`                                                          |
+| `ServerStatus` | `{playerCount, maxPlayerCount, ping}`; ping is milliseconds                                       |
+| `Ship`         | Listed ship: `id`, `hexCode`, `name`, `playerCount`, `owned`, `saved`, `color`, `iconUrl`, `time` |
+| `ShipList`     | `{ships, playerCount?, maxPlayerCount?, isMuted?}`                                                |
 
-Ship names in the returned objects are canonical Drednot server data. Leading
-and trailing spaces are preserved exactly; callers should not trim them.
+`fetchServers()` discovers servers; it does not populate status/ping fields. Discovery metadata is cached per origin for the process/module lifetime; repeated calls do not necessarily refetch the game version or directory. Discovery/status implementations also accept an optional final `baseUrl` argument, although the root declarations omit it. Ship names preserve leading and trailing spaces. Some ship metadata fields are nullable; inspect [declared shapes](../src/index.d.ts) when persisting results.
 
-### `Dredless.fetchInviteMetadata(invite, options?)`
+## Join, start, and invites
 
 ```ts
-function fetchInviteMetadata(
-  invite: string | URL,
-  options?: { includeColor?: boolean }
-): Promise<InviteMetadata>;
-```
+session.joinShip(server: ServerRef, ship?: ShipRef): Promise<DredlessClient>;
+session.startShip(server: ServerRef, ship?: ShipRef): Promise<DredlessClient>;
+session.startNewShip(server: ServerRef, name?: string, color?: string): Promise<DredlessClient>;
+session.joinInvite(server: ServerRef, code: string): Promise<DredlessClient>;
 
-Fetches and parses an invite page. The returned ship name preserves leading
-and trailing spaces exactly as returned by Drednot. Set `includeColor: true`
-to sample the preview image’s top-left pixel; otherwise no image is fetched.
-
-### `Dredless.joinShip(server, ship?, session?)`
-
-```ts
-function joinShip(
-  server: ServerRef,
-  ship?: ShipRef,
-  session?: Session | null
-): Promise<DredlessClient>;
+Dredless.joinShip(server: ServerRef, ship?: ShipRef, session?: Session | null): Promise<DredlessClient>;
+Dredless.startShip(server: ServerRef, ship?: ShipRef, session?: Session | null): Promise<DredlessClient>;
+Dredless.startNewShip(server: ServerRef, name?: string, color?: string,
+                      session?: Session | null): Promise<DredlessClient>;
+Dredless.joinInvite(server: ServerRef, code: string, session?: Session | null): Promise<DredlessClient>;
 ```
 
-Starts a websocket client using `never_load: true`. This is useful when you need
-to join without loading the full ship world.
+| Method         | Choose it when…                                                               |
+|----------------|-------------------------------------------------------------------------------|
+| `joinShip`     | The ship is active; joining must not load a saved ship (`never_load: true`)   |
+| `startShip`    | Joining may need to load/start the saved ship (`never_load: false`)           |
+| `startNewShip` | You intend to create a new ship; accepts a name and color such as `"#de9797"` |
+| `joinInvite`   | You have an invite code; accepts the code segment, not the URL                |
 
-If `session` is omitted, an anonymous session is created.
+The join/start distinction concerns loading a saved ship on the server. It is not a switch for partial versus full client world decoding. A `4007` rejection from `joinShip()` can mean the saved ship needs `startShip()`.
 
-### `Dredless.startShip(server, ship?, session?)`
+All client factories wait for the ready packet. [Lifecycle](CLIENT.md#completion-and-readiness) explains state availability and cleanup. Top-level factories create an anonymous session when `session` is omitted; pass your session explicitly to retain your identity.
 
 ```ts
-function startShip(
-  server: ServerRef,
-  ship?: ShipRef,
-  session?: Session | null
-): Promise<DredlessClient>;
+type ShipRef = number | string | Ship | ShipSpec | null;
+type ShipSpec =
+  | {type: "join_or_load"; id: number | string}
+  | {type: "new"; name?: string | null; color?: string | null}
+  | {type: "invite"; code: string};
 ```
 
-Starts a websocket client using normal world loading.
-
-If `session` is omitted, an anonymous session is created.
+Prefer a `Ship` object obtained from that server's list, or an explicit `ShipSpec`. Strings pass through as server ship selectors; do not assume every ID in every API uses the same format. Omitted/null ships use the method's default selection behavior.
 
-### `Dredless.startNewShip(server, name?, color?, session?)`
+### Read an invite preview
 
 ```ts
-function startNewShip(
-  server: ServerRef,
-  name?: string,
-  color?: string,
-  session?: Session | null
-): Promise<DredlessClient>;
+Dredless.fetchInviteMetadata(invite: string | URL,
+  options?: {fetchImpl?: typeof fetch}): Promise<InviteMetadata>;
 ```
 
-Creates/starts a new ship and returns a live client.
+This reads the public invite page without joining. It returns `{shipId, name, previewImageUrl, hostname, inviteCode}`. It does not fetch the preview image. Consumers can use `previewImageUrl` to implement their own image processing. Names preserve spacing. See [protocol tools](PROTOCOL.md#http-and-invite-tools) for the named parser export.
 
-### `Dredless.joinInvite(server, code, session?)`
+## Construct a client yourself
 
-```ts
-function joinInvite(
-  server: ServerRef,
-  code: string,
-  session?: Session | null
-): Promise<DredlessClient>;
-```
-
-Joins through an invite code and returns a live client.
-
-
-## `Session`
-
-`Session` represents an authenticated HTTP session and owns cookies, account
-status, ship list fetches, and `/join`.
+Use connection factories when you need listeners installed before connection:
 
 ```ts
-class Session {
-  constructor(gameSession?: string | null, gameVersion?: string | null);
-
-  baseUrl: string;
-  cookies: Map<string, string>;
-  gameVersion: string | null;
-  account: Account | null;
-  geoServer: number | null;
-  upgraded: boolean;
-  isRegistered: boolean;
-  showAds: boolean;
-  forceTutorial: boolean;
-  ban: unknown;
-
-  get gameSession(): string;
-  get gameToken(): string;
-  get noticeVersion(): number | string | null;
-  set noticeVersion(value: number | string | null);
-
-  request(path: string, init?: RequestInit & {
-    body?: BodyInit | Record<string, unknown> | null
-  }): Promise<Response>;
-
-  fetchAccountStatus(): Promise<unknown>;
-  fetchShips(server: ServerRef): Promise<Ship[]>;
-  fetchShipList(server: ServerRef): Promise<ShipList>;
-
-  joinShipConnection(server: ServerRef, ship?: ShipRef): Promise<Connection>;
-  startShipConnection(server: ServerRef, ship?: ShipRef): Promise<Connection>;
-  startNewShipConnection(
-    server: ServerRef,
-    name?: string,
-    color?: string
-  ): Promise<Connection>;
-  joinInviteConnection(server: ServerRef, code: string): Promise<Connection>;
-
-  joinShip(server: ServerRef, ship?: ShipRef): Promise<DredlessClient>;
-  startShip(server: ServerRef, ship?: ShipRef): Promise<DredlessClient>;
-  startNewShip(server: ServerRef, name?: string, color?: string): Promise<DredlessClient>;
-  joinInvite(server: ServerRef, code: string): Promise<DredlessClient>;
-
-  toJSON(): SessionSnapshot;
-}
-```
-
-### `new Session(gameSession?, gameVersion?)`
-
-Constructs an existing session wrapper. Does not perform network I/O.
-
-### `session.request(path, init?)`
-
-Authenticated HTTP helper. The `path` is relative to `session.baseUrl` unless a
-full URL is supplied by the implementation path handling.
-
-Input body may be a normal `BodyInit`, an object, or `null`.
-
-Returns the raw `Response`.
-
-### `session.fetchAccountStatus()`
-
-Fetches and applies account status. Returns the decoded server response as
-`unknown` because the live shape is not fully stabilized.
-
-### `session.fetchShips(server)`
-
-Returns `Ship[]`.
-
-### `session.fetchShipList(server)`
+session.joinShipConnection(server: ServerRef, ship?: ShipRef): Promise<Connection>;
+session.startShipConnection(server: ServerRef, ship?: ShipRef): Promise<Connection>;
+session.startNewShipConnection(server: ServerRef, name?: string, color?: string): Promise<Connection>;
+session.joinInviteConnection(server: ServerRef, code: string): Promise<Connection>;
 
-Returns `ShipList`.
-
-### Connection factories
-
-These return `Connection` objects and do not open the websocket:
-
-```ts
-session.joinShipConnection(server, ship?): Promise<Connection>;
-session.startShipConnection(server, ship?): Promise<Connection>;
-session.startNewShipConnection(server, name?, color?): Promise<Connection>;
-session.joinInviteConnection(server, code): Promise<Connection>;
+new Connection(session: Session, gameToken: string, netPort: number,
+               serverId: number | Server, server?: Server | null): Connection;
 ```
 
-Use these when you want to construct `DredlessClient` yourself.
-
-### Client factories
+A connection factory performs the HTTP join, returning a descriptor without opening the WebSocket. Constructing `Connection` itself performs no I/O.
 
-These return live `DredlessClient` objects:
+**Fragment:** `session`, `server`, and `code` come from the setup above:
 
-```ts
-session.joinShip(server, ship?): Promise<DredlessClient>;
-session.startShip(server, ship?): Promise<DredlessClient>;
-session.startNewShip(server, name?, color?): Promise<DredlessClient>;
-session.joinInvite(server, code): Promise<DredlessClient>;
-```
-
-### `session.toJSON()`
-
-```ts
-interface SessionSnapshot {
-  baseUrl: string;
-  gameSession: string;
-  gameToken: string;
-  gameVersion: string | null;
-  noticeVersion: number | string | null;
-  cookies: Record<string, string>;
-  account: Account | null;
-  geoServer: number | null;
-  upgraded: boolean;
-  isRegistered: boolean;
-  showAds: boolean;
-  forceTutorial: boolean;
-  ban: unknown;
-  anonKey?: string;
+```js
+const connection = await session.joinInviteConnection(server, code);
+const client = new DredlessClient(connection);
+client.on("error", (error) => console.error(error.message));
+client.on("model", ({world}) => console.log(world.id));
+try {
+  await client.whenReady();
+  // Keep using the client here, or attach application callbacks.
+} catch (error) {
+  client.close();
+  throw error;
 }
 ```
 
-## `AnonSession`
+See [client options](CLIENT.md#construction-and-retention) for history limits and offline construction.
+
+## HTTP requests
 
 ```ts
-class AnonSession extends Session {
-  constructor(
-    gameSession?: string | null,
-    anonKey?: string | null,
-    gameVersion?: string | null
-  );
-
-  get anonKey(): string;
-}
+session.request(path: string, init?: RequestInit & {body?: unknown}): Promise<Response>;
 ```
 
-`AnonSession` is a `Session` with anonymous account key handling.
+Paths resolve relative to `session.baseUrl`; an absolute URL is also accepted by the resolver. Requests attach the session cookie jar in Node. Use this authenticated helper for the session's intended origin.
 
-## `Connection`
+Strings, `ArrayBuffer`, and typed-array views pass through as bodies. Other objects are JSON-stringified; the helper sets JSON content type if none was supplied. It does not implement native Fetch handling for `URLSearchParams`, `FormData`, or `Blob` objects. For a form, pass `new URLSearchParams(fields).toString()` with an explicit form content type.
 
-`Connection` is a no-I/O descriptor for an already joined game session.
+The raw `Response` is returned. Callers of `request()` must check HTTP status themselves; it does not automatically reject on HTTP error codes or merge response cookies. Higher-level session methods do their own status/cookie handling.
 
-```ts
-class Connection {
-  constructor(
-    session: Session,
-    gameToken: string,
-    netPort: number,
-    serverId: number | Server,
-    server?: Server | null
-  );
-
-  session: Session;
-  baseUrl: string;
-  gameToken: string;
-  netPort: number;
-  serverId: number;
-  server: Server | null;
-
-  toJSON(): ConnectionSnapshot;
-}
-```
+## Serialization
 
-### `connection.toJSON()`
+`session.toJSON()` returns a `SessionSnapshot`: base URL, game session/token, cookies, game/notice versions, account status, and status flags. An anonymous session also includes `anonKey`. `connection.toJSON()` includes its session snapshot.
 
-```ts
-interface ConnectionSnapshot {
-  baseUrl: string;
-  gameToken: string;
-  netPort: number;
-  serverId: number;
-  server: Server | null;
-  session: SessionSnapshot;
-}
-```
+These snapshots contain credentials. Store them as credentials rather than logging them as ordinary state. No automatic persistence/restore helper is provided. When restoring a cookie jar yourself, use the snapshot's origin and cookie names, then refresh account status. [Account detail reads](ACCOUNT.md) do not add email or identity data to these snapshots.