onelobby 0.0.0-stage → 0.2.0

package/dist/onelobby.d.ts

@@ -0,0 +1,151 @@
+import { type Clock } from "./clock.js";
+import { Emitter } from "./emitter.js";
+import { Lobby, type RateLimit } from "./lobby.js";
+import { type LobbySummary } from "./signaling.js";
+import { type LinkFactory, type SocketFactory } from "./transport.js";
+import type { VoiceCodec, FrameSource, AudioSink } from "./voice-types.js";
+export declare const LIB_NAME = "onelobby";
+export declare const LIB_VERSION = "0.2.0";
+/** Where `rememberSeat` keeps the resume token: the subset of the Web Storage API it uses. */
+export interface SeatStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/** Seams for tests, adapters and non-browser runtimes. Every default is the browser implementation. */
+export interface AdvancedOptions {
+    socketFactory?: SocketFactory;
+    linkFactory?: LinkFactory;
+    clock?: Clock;
+    /** Wall clock in unix ms, stamps chat lines. */
+    wallClock?: () => number;
+    /** Opus codec; defaults to WebCodecs when available. Provide a WASM-backed one elsewhere. */
+    voiceCodec?: VoiceCodec | null;
+    createMic?: (() => FrameSource) | null;
+    createSink?: (() => AudioSink) | null;
+    /** Storage for `rememberSeat`; defaults to `sessionStorage` when the page has one. null disables it. */
+    storage?: SeatStorage | null;
+}
+export interface OneLobbyOptions {
+    gameId: string;
+    netVersion: string;
+    /** `ws://` / `wss://` URL of a onelobby-server. */
+    lobbyServer: string;
+    mode?: "lockstep" | "raw";
+    tickRate?: number;
+    /** Default: tickRate (once a second). */
+    hashEveryTicks?: number;
+    /** The player's name. Empty (the default): other players see "Player N", N being the seat number. */
+    displayName?: string;
+    relayOnly?: boolean;
+    /**
+     * Joiners give up on reaching the host after this many ms: `lobby.ready` rejects with code `ice_failed`, the kit
+     * emits `error`, and the lobby is left. Half the time goes to a relay-only retry when the server offers TURN.
+     * Default 15000; 0 waits forever.
+     */
+    readyTimeoutMs?: number;
+    /**
+     * Treat a peer as gone after this many ms of silence. Joiners ping the host every 2 s and the host answers, so the
+     * host drops a silent joiner (`peerLeft`, "timeout") and a joiner handles a silent host as lost (a direct lobby
+     * ends with "host_left"). Default 0 (off): a silently dead peer then surfaces when its link or signaling socket
+     * times out, within about 30 s. Values under 6000 are raised to 6000.
+     */
+    peerTimeoutMs?: number;
+    /**
+     * Keep this tab's seat across a page reload (sessionStorage): `join(code)` and `resume()` take the seat back
+     * instead of joining as a new player. Cleared when the session ends. Default true where sessionStorage exists.
+     */
+    rememberSeat?: boolean;
+    /** Test and runtime seams (see AdvancedOptions). */
+    advanced?: AdvancedOptions;
+    /** @deprecated use `advanced.socketFactory` */
+    socketFactory?: SocketFactory;
+    /** @deprecated use `advanced.linkFactory` */
+    linkFactory?: LinkFactory;
+    /** @deprecated use `advanced.clock` */
+    clock?: Clock;
+    /** @deprecated use `advanced.wallClock` */
+    wallClock?: () => number;
+    /** @deprecated use `advanced.voiceCodec` */
+    voiceCodec?: VoiceCodec | null;
+    /** @deprecated use `advanced.createMic` */
+    createMic?: (() => FrameSource) | null;
+    /** @deprecated use `advanced.createSink` */
+    createSink?: (() => AudioSink) | null;
+}
+export interface HostOptions {
+    name: string;
+    maxPlayers: number;
+    /**
+     * "unlisted" (default): anyone with the code or link can join, but the lobby is not in `list()`.
+     * "public": also listed. "private": the host approves each join.
+     */
+    visibility?: "public" | "unlisted" | "private";
+    lateJoin?: boolean;
+    meta?: Record<string, string>;
+    /** Per-joiner cap on incoming raw messages, e.g. `{ messages: 60, perMs: 1000 }`; the excess is dropped before `message` fires or is relayed. */
+    rateLimit?: RateLimit;
+}
+export interface ListOptions {
+    meta?: Record<string, string>;
+    limit?: number;
+    cursor?: string;
+}
+export interface JoinDirectOptions {
+    /** The host's password, if it set one; a wrong one fails with `bad_password`. */
+    password?: string;
+    /** Port for an address typed without one (default 47810, docs/direct-ip.md s.2). */
+    defaultPort?: number;
+    /** No answer on the host's TCP port within this long fails with `direct_unreachable` (default 5000). */
+    connectTimeoutMs?: number;
+}
+/** @internal How onelobby/direct makes a host lobby: its own socket and link factory, and direct mode. */
+export interface DirectLobbyHooks {
+    socketFactory: SocketFactory;
+    /** Wraps the kit's own link factory (port pin, no ICE servers). */
+    wrapLinks: (inner: LinkFactory) => LinkFactory;
+}
+export type OneLobbyEvents = {
+    error: [Error];
+};
+export declare const DEFAULT_READY_TIMEOUT_MS = 15000;
+/** Entry point (DESIGN s.11.2). */
+export declare class OneLobby extends Emitter<OneLobbyEvents> {
+    readonly options: Required<Pick<OneLobbyOptions, "gameId" | "netVersion" | "lobbyServer" | "mode" | "tickRate" | "hashEveryTicks" | "displayName" | "relayOnly" | "readyTimeoutMs" | "peerTimeoutMs">>;
+    private socketFactory;
+    private linkFactory;
+    private clock;
+    private wall;
+    private voiceCodec;
+    private createMic;
+    private createSink;
+    private storage;
+    constructor(o: OneLobbyOptions);
+    private get seatKey();
+    private loadSeat;
+    private saveSeat;
+    private clearSeat;
+    /** The lobby code of the seat this tab can take back (rememberSeat), or null. */
+    get rememberedCode(): string | null;
+    /**
+     * Take back the seat remembered from before a page reload (host or joiner). Resolves null when there is none
+     * or the server no longer holds it (the seat is forgotten then).
+     */
+    resume(): Promise<Lobby | null>;
+    private helloMsg;
+    private connect;
+    private makeLobby;
+    host(h: HostOptions): Promise<Lobby>;
+    join(code: string): Promise<Lobby>;
+    /**
+     * Join a direct-IP host (docs/direct-ip.md): a join code from the host's screen (`6B01-RGFE-P2B`, any case, spaces
+     * or hyphens) or, advanced, an address (`ip`, `ip:port`, `[v6]:port`). No lobby server is involved: the code is
+     * the host's address. A mistyped code fails at once with `bad_code`; nobody listening is `direct_unreachable`.
+     * The address is also given to ICE as the host's UDP candidate. When the host leaves, `sessionEnded("host_left")`.
+     */
+    joinDirect(codeOrAddress: string, opts?: JoinDirectOptions): Promise<Lobby>;
+    /** @internal onelobby/direct's host: create the one lobby on the embedded hub, in direct mode. */
+    hostDirectWith(h: HostOptions, hooks: DirectLobbyHooks): Promise<Lobby>;
+    rejoin(resumeToken: string): Promise<Lobby>;
+    list(opts?: ListOptions): Promise<LobbySummary[]>;
+}