onelobby 0.4.1 → 0.6.0

package/dist/onelobby.d.ts

@@ -4,8 +4,11 @@ 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";
+import { type RelayConnect } from "./nostr/relays.js";
+import { type Blueprint } from "./blueprint.js";
+import { type BrowserHostOptions } from "./direct/browser-host.js";
 export declare const LIB_NAME = "onelobby";
-export declare const LIB_VERSION = "0.4.1";
+export declare const LIB_VERSION = "0.6.0";
 /** Where `rememberSeat` keeps the resume token: the subset of the Web Storage API it uses. */
 export interface SeatStorage {
     getItem(key: string): string | null;
@@ -25,6 +28,8 @@ export interface AdvancedOptions {
     createSink?: (() => AudioSink) | null;
     /** Storage for `rememberSeat`; defaults to `sessionStorage` when the page has one. null disables it. */
     storage?: SeatStorage | null;
+    /** WebSocket to a Nostr relay (default: the runtime's `WebSocket`); for Node older than 22 or tests. */
+    nostrConnect?: RelayConnect;
 }
 export interface OneLobbyOptions {
     gameId: string;
@@ -73,6 +78,16 @@ export interface OneLobbyOptions {
     /** @deprecated use `advanced.createSink` */
     createSink?: (() => AudioSink) | null;
 }
+/** Per-launch settings for `OneLobby.fromConfig`; everything else comes from the blueprint. */
+export interface FromConfigOverrides {
+    /** The player's name. Checked against `players.identity` and `players.maxNameLength`. */
+    displayName?: string;
+    /** Wins over `hosting.lobbyServer` (the file is the bottom layer: put `?lobby=` / storage / `<meta>` lookups here). */
+    lobbyServer?: string;
+    /** Default: `lobby.rejoin` from the file. */
+    rememberSeat?: boolean;
+    advanced?: AdvancedOptions;
+}
 export interface HostOptions {
     name: string;
     maxPlayers: number;
@@ -94,10 +109,14 @@ export interface ListOptions {
 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). */
+    /** Port for an address typed without one (default 47810, docs/design/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;
+    /** Nostr relays for a Nostr code (version 1); default the blueprint's `hosting.nostrRelays`, else the library list. */
+    nostrRelays?: string[];
+    /** STUN servers for a Nostr code when the host offers none; default Google's and Cloudflare's public ones. */
+    stun?: string[];
 }
 /** @internal How onelobby/direct makes a host lobby: its own socket and link factory, and direct mode. */
 export interface DirectLobbyHooks {
@@ -120,6 +139,17 @@ export declare class OneLobby extends Emitter<OneLobbyEvents> {
     private createMic;
     private createSink;
     private storage;
+    private nostrConnectFn;
+    /** The validated, frozen onelobby.json this kit was built from (`OneLobby.fromConfig`); undefined for `new OneLobby`. */
+    readonly blueprint?: Blueprint;
+    /**
+     * Build a kit from an onelobby.json (already parsed; docs/design/blueprint.md s.7). Throws `bad_config` for an
+     * invalid file or name, `identity_anonymous` for a name when `players.identity` is "anonymous". Then `host()` and
+     * `hostDirect()` default their options from the file and the file's chat/listing switches are enforced.
+     */
+    static fromConfig(json: unknown, overrides?: FromConfigOverrides): OneLobby;
+    /** @internal Host options the blueprint implies (empty without one). */
+    blueprintHostDefaults(): Partial<HostOptions>;
     constructor(o: OneLobbyOptions);
     private get seatKey();
     private loadSeat;
@@ -137,10 +167,11 @@ export declare class OneLobby extends Emitter<OneLobbyEvents> {
     /** The signaling socket only (no hello yet); with a timeout (direct IP), no answer is `direct_unreachable`. */
     private open;
     private makeLobby;
-    host(h: HostOptions): Promise<Lobby>;
+    /** With a blueprint (`fromConfig`) every option defaults from `lobby.*`; explicit options win. */
+    host(opts?: Partial<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
+     * Join a direct-IP host (docs/design/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")`.
@@ -152,9 +183,28 @@ export declare class OneLobby extends Emitter<OneLobbyEvents> {
      * same peer id comes back. Rejects with `invalid_token` when the seat is gone: offer `joinDirect` then.
      */
     rejoinDirect(codeOrAddress: string, resumeToken: string, opts?: JoinDirectOptions): Promise<Lobby>;
+    private nostrFactory;
+    /** Opens the signaling socket of a direct target: TCP to the host's address, or Nostr relays for a version 1 code. */
+    private connectDirect;
+    /** A Nostr joiner needs STUN; take the host's list (it comes in `welcome`), else the public defaults. */
+    private withStun;
     private directTarget;
+    /** @internal onelobby/direct's Nostr host: the relay seam and the kit's clocks. */
+    nostrHostEnv(): {
+        connect: RelayConnect | undefined;
+        clock: Clock;
+        wall: () => number;
+    };
     /** @internal onelobby/direct's host: create the one lobby on the embedded hub, in direct mode. */
     hostDirectWith(h: HostOptions, hooks: DirectLobbyHooks): Promise<Lobby>;
+    /**
+     * Host a direct lobby from this browser tab (or any runtime with WebSocket and WebRTC): no Node process, no port.
+     * The hub runs in the page and joiners find it through Nostr relays with `lobby.joinCode` (a dc1 version 1 code,
+     * `joinCodeKind` "nostr"); they use `kit.joinDirect(code)`. Rejects with `direct_unreachable` when no relay answers
+     * within 10 s (a browser has no IP fallback) and `nostr_disabled` when the blueprint has `hosting.nostr` false.
+     * Keep the tab visible: hidden tabs are throttled (`lobby.hostHidden`, event `hostHiddenChanged`).
+     */
+    hostNostr(opts?: BrowserHostOptions): Promise<Lobby>;
     rejoin(resumeToken: string): Promise<Lobby>;
     private resumeAt;
     list(opts?: ListOptions): Promise<LobbySummary[]>;