dredless 0.2.0

package/docs/BROWSER_API.md

@@ -0,0 +1,98 @@
+# Dredless Browser API
+
+This document covers the browser-specific top-level API: ambient browser sessions, browser cookie handling, and browser start/join helpers.
+
+Use this entrypoint in browser contexts:
+
+```js
+import Dredless, { BrowserSession } from "dredless/browser";
+```
+
+Normal browser usage:
+
+```js
+const session = await Dredless.createAnonSession();
+const servers = await Dredless.fetchServers();
+const ships = await Dredless.fetchShips(servers[0]);
+const client = await Dredless.startShip(servers[0], ships[0]);
+```
+
+The browser API uses the current browser cookie jar with `credentials: "include"`. Browser JavaScript cannot read `Set-Cookie`, cannot set the `Cookie` header, and cannot set custom WebSocket headers, so browser authentication is ambient rather than multi-session.
+
+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).
+
+## `DredlessBrowser` Namespace
+
+`dredless/browser` exports a browser-first namespace. It assumes the current browser cookie jar and does not expose `Session` or `AnonSession`.
+
+```ts
+interface DredlessBrowserNamespace {
+  BrowserSession: typeof BrowserSession;
+  Connection: typeof Connection;
+  DredlessClient: typeof DredlessClient;
+  browserSession: typeof browserSession;
+  createBrowserSession: typeof createBrowserSession;
+  createSession: typeof createSession;
+  createAnonSession: typeof createAnonSession;
+  createAnonToken: typeof createAnonToken;
+  fetchAnonKey: typeof fetchAnonKey;
+  setBrowserSession: typeof setBrowserSession;
+  fetchAccountStatus: typeof fetchAccountStatus;
+  fetchNoticeVersion: typeof fetchNoticeVersion;
+  fetchGameVersion: typeof fetchGameVersion;
+  fetchServers: typeof fetchServers;
+  fetchShips: typeof fetchShips;
+  fetchShipList: typeof fetchShipList;
+  joinShip: typeof joinShip;
+  startShip: typeof startShip;
+  startNewShip: typeof startNewShip;
+  joinInvite: typeof joinInvite;
+}
+```
+
+`createSession(noticeVersion?, baseUrl?)` initializes the ambient browser session, fetches account status, and returns the active `BrowserSession`.
+
+`createAnonSession(anonKey?, noticeVersion?, baseUrl?)` creates or applies an anonymous browser session. If `anonKey` is omitted, it posts to `/account/login/anon`, then reads `anon_key` through `cookieStore` or `document.cookie`. If the key cannot be read, it throws. If `anonKey` is provided, it is written to the ambient cookie jar when possible. The return value is still the active `BrowserSession`, not an isolated cookie jar.
+
+`fetchAnonKey(noticeVersion?, baseUrl?)` / `createAnonToken(noticeVersion?, baseUrl?)` posts to `/account/login/anon` and returns the JS-readable `anon_key`. It throws if the login succeeds but the key is not readable through `cookieStore` or `document.cookie`.
+
+Browser support is tested in page and content-script contexts on `drednot.io`. Background pages, popups, workers, and other non-page contexts are unlikely to expose `drednot.io` cookies to this API.
+
+`fetchShips(server)` and `fetchShipList(server)` use the default ambient `BrowserSession`. Pass an explicit `BrowserSession` as the last argument only when targeting a different `baseUrl`.
+
+`joinShip`, `startShip`, `startNewShip`, and `joinInvite` return ready `DredlessClient` instances just like the Node helpers.
+
+## `BrowserSession`
+
+`BrowserSession` is the browser counterpart to `Session`, but it is ambient-cookie based. It cannot read `Set-Cookie` and cannot set websocket headers, so authentication must be accepted by the browser's cookie jar.
+
+```ts
+class BrowserSession {
+  constructor(baseUrl?: string);
+  baseUrl: string;
+  ambientAuth: true;
+
+  readAnonKey(): Promise<string>;
+  fetchAnonKey(noticeVersion?: number | null): Promise<string>;
+  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>;
+}
+```
+
+
+## Browser Connections
+
+Browser start/join helpers still produce `Connection` objects internally, but a browser `Connection` may have an empty `gameToken` when the token is only available through browser-managed cookies. `DredlessClient` uses the browser `WebSocket` implementation and relies on browser-managed cookies and origin headers.
+
+The shared `DredlessClient` API is documented in [API_REFERENCE.md](./API_REFERENCE.md#dredlessclient).

package/docs/NODE_API.md

@@ -0,0 +1,359 @@
+# Dredless Node API
+
+This document covers the Node-specific top-level API: explicit sessions, anonymous token/session creation, connection descriptors, and convenience start/join helpers.
+
+Use this entrypoint when you want the multi-session cookie-jar API:
+
+```js
+import Dredless, {
+  Session,
+  AnonSession,
+  Connection,
+  DredlessClient
+} from "dredless/node";
+```
+
+Normal Node usage:
+
+```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;
+  joinShip: typeof joinShip;
+  startShip: typeof startShip;
+  startNewShip: typeof startNewShip;
+  joinInvite: typeof joinInvite;
+}
+```
+
+### `Dredless.createSession(noticeVersion?)`
+
+```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?)`
+
+```ts
+function createAnonSession(
+  anonKey?: string | null,
+  noticeVersion?: number | null,
+  baseUrl?: string
+): Promise<AnonSession>;
+```
+
+Creates an anonymous session. If `anonKey` is omitted, the library requests one
+from the server.
+
+Returns an `AnonSession`.
+
+### `Dredless.createAnonToken(noticeVersion?, baseUrl?)`
+
+```ts
+function createAnonToken(
+  noticeVersion?: number | null,
+  baseUrl?: string
+): Promise<string>;
+```
+
+Requests a new anonymous account token.
+
+### `Dredless.fetchNoticeVersion()`
+
+```ts
+function fetchNoticeVersion(): Promise<number>;
+```
+
+Scrapes the current notice version needed by anon login.
+
+### `Dredless.fetchGameVersion()`
+
+```ts
+function fetchGameVersion(): Promise<string>;
+```
+
+Scrapes the current game version string from the site.
+
+### `Dredless.fetchServers()`
+
+```ts
+function fetchServers(): Promise<Server[]>;
+```
+
+Scrapes and returns known game servers.
+
+### `Dredless.fetchShips(session, server)`
+
+```ts
+function fetchShips(session: Session, server: ServerRef): Promise<Ship[]>;
+```
+
+Authenticated convenience wrapper around `session.fetchShips(server)`.
+
+### `Dredless.fetchShipList(session, server)`
+
+```ts
+function fetchShipList(session: Session, server: ServerRef): Promise<ShipList>;
+```
+
+Authenticated convenience wrapper around `session.fetchShipList(server)`.
+
+### `Dredless.joinShip(server, ship?, session?)`
+
+```ts
+function joinShip(
+  server: ServerRef,
+  ship?: ShipRef,
+  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.
+
+If `session` is omitted, an anonymous session is created.
+
+### `Dredless.startShip(server, ship?, session?)`
+
+```ts
+function startShip(
+  server: ServerRef,
+  ship?: ShipRef,
+  session?: Session | null
+): Promise<DredlessClient>;
+```
+
+Starts a websocket client using normal world loading.
+
+If `session` is omitted, an anonymous session is created.
+
+### `Dredless.startNewShip(server, name?, color?, session?)`
+
+```ts
+function startNewShip(
+  server: ServerRef,
+  name?: string,
+  color?: string,
+  session?: Session | null
+): Promise<DredlessClient>;
+```
+
+Creates/starts a new ship and returns a live client.
+
+### `Dredless.joinInvite(server, code, session?)`
+
+```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`.
+
+```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)`
+
+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>;
+```
+
+Use these when you want to construct `DredlessClient` yourself.
+
+### Client factories
+
+These return live `DredlessClient` objects:
+
+```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;
+}
+```
+
+## `AnonSession`
+
+```ts
+class AnonSession extends Session {
+  constructor(
+    gameSession?: string | null,
+    anonKey?: string | null,
+    gameVersion?: string | null
+  );
+
+  get anonKey(): string;
+}
+```
+
+`AnonSession` is a `Session` with anonymous account key handling.
+
+## `Connection`
+
+`Connection` is a no-I/O descriptor for an already joined game session.
+
+```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;
+}
+```
+
+### `connection.toJSON()`
+
+```ts
+interface ConnectionSnapshot {
+  baseUrl: string;
+  gameToken: string;
+  netPort: number;
+  serverId: number;
+  server: Server | null;
+  session: SessionSnapshot;
+}
+```
+

package/package.json

@@ -0,0 +1,173 @@
+{
+    "name": "dredless",
+    "version": "0.2.0",
+    "description": "A from-scratch simple headless drednot.io client.",
+    "license": "MIT",
+    "homepage": "https://github.com/certainhuman/dredless#readme",
+    "repository": {
+        "type": "git",
+        "url": "git+ssh://git@github.com/certainhuman/dredless.git"
+    },
+    "bugs": {
+        "url": "https://github.com/certainhuman/dredless/issues"
+    },
+    "keywords": [
+        "drednot",
+        "drednot.io",
+        "headless",
+        "websocket"
+    ],
+    "type": "module",
+    "main": "src/index.js",
+    "types": "./src/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./src/index.d.ts",
+            "browser": "./src/browser.js",
+            "node": "./src/node.js",
+            "import": "./src/index.js",
+            "default": "./src/index.js"
+        },
+        "./browser": {
+            "types": "./src/browser.d.ts",
+            "import": "./src/browser.js",
+            "default": "./src/browser.js"
+        },
+        "./node": {
+            "types": "./src/node.d.ts",
+            "import": "./src/node.js",
+            "default": "./src/node.js"
+        },
+        "./client": {
+            "types": "./src/client/index.d.ts",
+            "import": "./src/client/index.js",
+            "default": "./src/client/index.js"
+        },
+        "./session": {
+            "types": "./src/network/session.d.ts",
+            "import": "./src/network/session.js",
+            "default": "./src/network/session.js"
+        },
+        "./servers": {
+            "types": "./src/network/servers.d.ts",
+            "import": "./src/network/servers.js",
+            "default": "./src/network/servers.js"
+        },
+        "./ships": {
+            "types": "./src/network/ships.d.ts",
+            "import": "./src/network/ships.js",
+            "default": "./src/network/ships.js"
+        },
+        "./connection": {
+            "types": "./src/network/connection.d.ts",
+            "import": "./src/network/connection.js",
+            "default": "./src/network/connection.js"
+        },
+        "./world": {
+            "types": "./src/state/world/index.d.ts",
+            "import": "./src/state/world/index.js",
+            "default": "./src/state/world/index.js"
+        },
+        "./model": {
+            "types": "./src/state/model/index.d.ts",
+            "import": "./src/state/model/index.js",
+            "default": "./src/state/model/index.js"
+        },
+        "./network": {
+            "types": "./src/network/index.d.ts",
+            "import": "./src/network/index.js",
+            "default": "./src/network/index.js"
+        },
+        "./state": {
+            "types": "./src/state/index.d.ts",
+            "import": "./src/state/index.js",
+            "default": "./src/state/index.js"
+        },
+        "./protocol": {
+            "types": "./src/protocol/index.d.ts",
+            "import": "./src/protocol/index.js",
+            "default": "./src/protocol/index.js"
+        },
+        "./game/generator-maze": {
+            "types": "./src/state/generator-maze.d.ts",
+            "import": "./src/state/generator-maze.js",
+            "default": "./src/state/generator-maze.js"
+        },
+        "./game/model": {
+            "types": "./src/state/model/index.d.ts",
+            "import": "./src/state/model/index.js",
+            "default": "./src/state/model/index.js"
+        },
+        "./protocol/msgpack": {
+            "types": "./src/protocol/codec/msgpack.d.ts",
+            "import": "./src/protocol/codec/msgpack.js",
+            "default": "./src/protocol/codec/msgpack.js"
+        },
+        "./protocol/blueprint": {
+            "types": "./src/protocol/outbound/blueprint.d.ts",
+            "import": "./src/protocol/outbound/blueprint.js",
+            "default": "./src/protocol/outbound/blueprint.js"
+        },
+        "./protocol/comms": {
+            "types": "./src/protocol/outbound/comms.d.ts",
+            "import": "./src/protocol/outbound/comms.js",
+            "default": "./src/protocol/outbound/comms.js"
+        },
+        "./protocol/commands": {
+            "types": "./src/protocol/outbound/commands.d.ts",
+            "import": "./src/protocol/outbound/commands.js",
+            "default": "./src/protocol/outbound/commands.js"
+        },
+        "./protocol/inventory": {
+            "types": "./src/protocol/outbound/inventory.d.ts",
+            "import": "./src/protocol/outbound/inventory.js",
+            "default": "./src/protocol/outbound/inventory.js"
+        },
+        "./protocol/ship-management": {
+            "types": "./src/protocol/outbound/ship-management.d.ts",
+            "import": "./src/protocol/outbound/ship-management.js",
+            "default": "./src/protocol/outbound/ship-management.js"
+        },
+        "./protocol/sign": {
+            "types": "./src/protocol/outbound/sign.d.ts",
+            "import": "./src/protocol/outbound/sign.js",
+            "default": "./src/protocol/outbound/sign.js"
+        },
+        "./protocol/ui-config": {
+            "types": "./src/protocol/outbound/ui-config.d.ts",
+            "import": "./src/protocol/outbound/ui-config.js",
+            "default": "./src/protocol/outbound/ui-config.js"
+        },
+        "./crypto/chacha": {
+            "types": "./src/crypto/chacha.d.ts",
+            "import": "./src/crypto/chacha.js",
+            "default": "./src/crypto/chacha.js"
+        },
+        "./compression/lz4": {
+            "types": "./src/compression/lz4.d.ts",
+            "import": "./src/compression/lz4.js",
+            "default": "./src/compression/lz4.js"
+        }
+    },
+    "dependencies": {
+        "ws": "^8.18.0"
+    },
+    "files": [
+        "src",
+        "docs",
+        "README.md"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "check": "node scripts/check-syntax.js",
+        "test": "node --test \"test/*.test.js\"",
+        "pack:check": "npm pack --dry-run",
+        "prepublishOnly": "npm run check && npm test",
+        "update:item-schema": "node scripts/update-item-schema.js"
+    },
+    "devDependencies": {
+        "dsa-shipshape": "^0.1.2"
+    }
+}