interface SubscribeOptions {
    /**
     * When true, the server stamps each broadcast message on this
     * channel with the sender's JWT `peerMetadata` claim as
     * `fromMetadata`. Opt-in because the metadata may contain customer
     * PII (display name, avatar URL) that not every subscriber needs.
     * Default false.
     */
    includeSenderMetadata?: boolean;
}
type PublishOptions = Record<string, never>;
type SendOptions = Record<string, never>;
interface WelcomePayload {
    peerId: string;
    /** Unix-second expiry of the JWT, or null for pk_ keys (no expiry). */
    expiresAt: number | null;
    serverTime: number;
    maxMessageSize: number;
    /**
     * Opaque metadata pass-through from the JWT `metadata` claim. The
     * wire protocol treats this as a generic JSON bag — the server
     * doesn't interpret it. WebRTC customers put TURN credentials at
     * `metadata.iceServers` by convention; the SDK reads them from there
     * and surfaces them on the `connected` event for the WebRTC layer to
     * consume.
     */
    metadata?: Record<string, unknown>;
}
/**
 * JSON-serializable mirror of the DOM `RTCIceServer` dictionary.
 * Declared here (rather than importing the DOM type) so this file
 * stays a pure wire-protocol definition usable in Node + non-DOM
 * contexts. Not a wire-protocol field itself — peer-lib extracts
 * iceServers from `metadata.iceServers` by convention.
 */
interface IceServerConfig {
    urls: string | string[];
    username?: string;
    credential?: string;
}
/** Channel broadcast — server-side type is "message". */
interface MessageEvent {
    channel: string;
    from: string;
    fromMetadata?: Record<string, unknown>;
    data: unknown;
}
/** Direct point-to-point send. Server-side type is "direct". */
interface DirectMessageEvent {
    from: string;
    fromMetadata?: Record<string, unknown>;
    data: unknown;
}
interface PresencePeer {
    peerId: string;
    metadata?: Record<string, unknown>;
}
interface PresenceEvent {
    channel: string;
    joined: PresencePeer[];
    left: PresencePeer[];
}
interface ServerErrorEvent {
    /** Echo of the client's `requestId` when correlatable. */
    requestId?: string;
    /**
     * Machine-readable error code. The `ErrorCode` union lists the
     * codes known to this SDK version; the field is deliberately open
     * (`string`) so a NEWER server's codes still flow through — a
     * correlated request rejects immediately with the real code instead
     * of timing out, and uncorrelated ones surface on `server-error`.
     * Branch with equality checks, not exhaustive switches.
     *
     * (`ErrorCode | (string & {})` keeps IDE autocomplete for the known
     * codes while accepting any string.)
     */
    code: ErrorCode | (string & {});
    message?: string;
}
interface GoingAwayEvent {
    /** Hint for clients with custom backoff — typical value 1000. */
    retryAfterMs: number;
}
/** Stable machine-readable error codes from the server's `error` frames. */
type ErrorCode = "malformed_message" | "unknown_type" | "invalid_channel" | "invalid_peer_id" | "channel_not_authorized" | "channel_reserved" | "channel_limit_exceeded" | "peer_not_found" | "missing_data" | "action_not_permitted" | "over_message_quota";
/**
 * WebSocket close codes the server may emit. Re-exported as a const
 * object (NOT enum) for tree-shakability and so customers can branch
 * on a runtime value without importing types-only.
 */
declare const WsCloseCode: {
    readonly GoingAway: 1001;
    readonly PolicyViolation: 1008;
    readonly MessageTooBig: 1009;
    readonly ClientInactivity: 4000;
    readonly InvalidToken: 4001;
    readonly TokenExpired: 4002;
    readonly ChannelNotAuthorized: 4003;
    readonly OverConcurrentLimit: 4010;
    readonly OverMessageRate: 4011;
    readonly AccountSuspended: 4012;
    readonly AdminDisconnect: 4020;
};
type WsCloseCode = (typeof WsCloseCode)[keyof typeof WsCloseCode];

/**
 * Error thrown when the server closes the connection with a 4xxx
 * close code (auth failure, quota exceeded, admin kick). The
 * `closeCode` field lets customers branch on the specific reason.
 *
 * `message` is a fixed string that NEVER interpolates server-supplied
 * `reason` text — a malicious server could otherwise stuff control
 * characters or HTML-ish content into a customer's
 * `console.error(err.message)` output, or into a UI surface that
 * renders `error.message`. The full server reason is available as
 * the `closeReason` field for customers who explicitly need it.
 */
declare class SignallingConnectError extends Error {
    readonly closeCode: number;
    readonly closeReason: string;
    constructor(closeCode: number, closeReason: string);
}
/**
 * Thrown by `publish()` / `send()` when the JSON-serialized payload
 * exceeds the server's per-message cap (advertised on the `connected`
 * event as `maxMessageSize`). Rejecting client-side keeps the
 * connection alive — an oversized frame reaching the server would
 * close the socket with code 1009 and take every subscription down
 * with it. Branch on `instanceof` or `err.name ===
 * "OversizedPayloadError"`; the `size` / `cap` fields carry the
 * measured payload size and the active limit in bytes.
 */
declare class OversizedPayloadError extends Error {
    readonly name = "OversizedPayloadError";
    readonly size: number;
    readonly cap: number;
    constructor(size: number, cap: number);
}

/** Drops every log. Default when the customer doesn't supply one. */
declare const NoopLogger: Logger;
/**
 * Routes to globalThis.console with level-named methods. Useful in
 * dev; customers should swap in their structured logger for prod.
 */
declare const ConsoleLogger: Logger;

type Handler<P> = (payload: P) => void;
interface EventEmitterOptions {
    /**
     * Invoked when a listener throws. Defaults to console.error so
     * the failure is visible during development; production consumers
     * can swap to their logger via the SignallingClient logger option.
     */
    onListenerError?: (err: unknown, eventName: string) => void;
    /**
     * Warn (via onListenerWarn or the default console.warn) when an
     * event's listener count crosses this threshold — typical signal
     * for a React-useEffect-without-cleanup leak. Default 100. The
     * warning fires ONCE per event-name as the count crosses the
     * threshold; further additions don't re-warn until the count drops
     * below and crosses again.
     */
    maxListenersWarn?: number;
    onListenerWarn?: (msg: string, ctx: Record<string, unknown>) => void;
}
declare class EventEmitter<EventMap> {
    private readonly listeners;
    private readonly onListenerError;
    private readonly maxListenersWarn;
    private readonly onListenerWarn;
    private readonly warnedEvents;
    constructor(opts?: EventEmitterOptions);
    on<K extends keyof EventMap>(event: K, handler: Handler<EventMap[K]>): this;
    /**
     * Remove a previously-registered handler. Noop if the handler ref
     * isn't currently registered (matches Node's behaviour — silent).
     * Only removes the FIRST matching entry so `on(e, h); on(e, h);`
     * needs two off() calls to fully unregister, again matching Node.
     */
    off<K extends keyof EventMap>(event: K, handler: Handler<EventMap[K]>): this;
    /**
     * Emit a one-shot warning when an event's listener count crosses
     * the threshold for the first time (or after dropping back below
     * and re-crossing). Customers add listeners in many places —
     * React useEffects, addEventListener-style integrations — so a
     * runaway count usually points at a missing cleanup hook.
     */
    private checkListenerCountThreshold;
    /**
     * Register a one-shot handler. The wrapper auto-removes itself
     * BEFORE invoking the customer's handler, so a handler that
     * re-emits the same event won't infinite-loop (defensive — Node
     * orders the cleanup before invocation for the same reason).
     */
    once<K extends keyof EventMap>(event: K, handler: Handler<EventMap[K]>): this;
    /**
     * Synchronous dispatch in registration order. Snapshots the list
     * first so a handler that calls .off() on itself or another
     * listener during dispatch doesn't trip the iteration.
     */
    emit<K extends keyof EventMap>(event: K, payload: EventMap[K]): boolean;
    /** Test / introspection helper. */
    listenerCount<K extends keyof EventMap>(event: K): number;
    /** Remove every handler for every event. */
    removeAllListeners(): this;
}

/**
 * Per-remote-peer lifecycle state. Coarser than the underlying
 * RTCPeerConnection states so the public API stays stable across
 * spec evolution. Mapping (driven by connectionState):
 *
 *   idle:         constructed but no negotiation kicked off yet
 *   connecting:   RTCPeerConnection.connectionState in {new, connecting}
 *   connected:    connectionState === "connected"
 *   reconnecting: connectionState === "disconnected" (transient)
 *                 OR "failed" (ICE restart pending)
 *   closed:       connectionState === "closed" — terminal
 */
type PeerConnectionState = "idle" | "connecting" | "connected" | "reconnecting" | "closed";
interface PeerConnectionLogger {
    debug?(msg: string, ctx?: Record<string, unknown>): void;
    warn?(msg: string, ctx?: Record<string, unknown>): void;
    error?(msg: string, ctx?: Record<string, unknown>): void;
}
/**
 * Subset of RTCPeerConnection the wrapper uses. Production passes
 * the platform constructor (browser globalThis.RTCPeerConnection or
 * node's `wrtc` binding) via `rtcPeerConnectionFactory`. Tests pass
 * a fake. Structural compat: a real RTCPeerConnection satisfies this
 * by virtue of being a superset.
 *
 * Defined explicitly (not `Pick<RTCPeerConnection, ...>`) because the
 * DOM types include legacy callback-style overloads on createOffer /
 * createAnswer / setLocalDescription that the fake can't satisfy.
 * Only the modern Promise-based signatures matter here.
 */
interface RTCPeerConnectionLike {
    readonly connectionState: RTCPeerConnectionState;
    readonly signalingState: RTCSignalingState;
    readonly iceConnectionState: RTCIceConnectionState;
    readonly localDescription: RTCSessionDescription | null;
    readonly remoteDescription: RTCSessionDescription | null;
    createOffer(options?: RTCOfferOptions): Promise<RTCSessionDescriptionInit>;
    createAnswer(options?: RTCAnswerOptions): Promise<RTCSessionDescriptionInit>;
    setLocalDescription(description?: RTCSessionDescriptionInit): Promise<void>;
    setRemoteDescription(description: RTCSessionDescriptionInit): Promise<void>;
    addIceCandidate(candidate?: RTCIceCandidateInit | null): Promise<void>;
    addTrack(track: MediaStreamTrack, ...streams: MediaStream[]): RTCRtpSender;
    removeTrack(sender: RTCRtpSender): void;
    getSenders(): RTCRtpSender[];
    createDataChannel(label: string, dataChannelDict?: RTCDataChannelInit): RTCDataChannel;
    /**
     * Update ICE servers (typically refreshed TURN credentials) on a
     * live connection. The spec restricts which fields can change here
     * — iceServers is one that's allowed; bundlePolicy isn't, post-construction.
     */
    setConfiguration(configuration?: RTCConfiguration): void;
    addEventListener(type: string, listener: (ev: unknown) => void): void;
    removeEventListener(type: string, listener: (ev: unknown) => void): void;
    close(): void;
}
/**
 * Subset of RTCDataChannel the DataChannel wrapper relies on.
 * Production: the underlying RTCDataChannel returned by
 * RTCPeerConnection.createDataChannel or surfaced via the
 * `datachannel` event. Tests: a fake supplying the same surface.
 *
 * Mutable bufferedAmountLowThreshold (the spec has it writable). All
 * other state is read-only on RTCDataChannel.
 */
interface RTCDataChannelLike {
    readonly label: string;
    readonly readyState: RTCDataChannelState;
    readonly bufferedAmount: number;
    bufferedAmountLowThreshold: number;
    send(data: string | ArrayBuffer): void;
    close(): void;
    addEventListener(type: string, listener: (ev: unknown) => void): void;
    removeEventListener(type: string, listener: (ev: unknown) => void): void;
}
interface DataChannelOptions {
    /**
     * Backpressure ceiling. `send()` won't actually call the underlying
     * channel.send() until `bufferedAmount` is below this number. Default
     * 1_048_576 (1 MB) — a reasonable browser-default cap that avoids
     * unbounded memory growth when the producer outruns the link.
     */
    maxBufferedAmount?: number;
    /**
     * Threshold at which the channel emits `bufferedamountlow`. Default
     * is `maxBufferedAmount / 2`. The wrapper sets this on the underlying
     * channel; customers can override per-instance if they need finer
     * control over the drain cadence.
     */
    bufferedAmountLowThreshold?: number;
    /**
     * Maximum sends queued behind the backpressure chain. Past this,
     * `send()` rejects synchronously with `DataChannelOverflowError`
     * rather than letting the JS heap grow unboundedly while waiting
     * on a stalled link. Default 256.
     */
    maxQueuedSends?: number;
    logger?: PeerConnectionLogger;
}
interface DataChannelEventMap {
    open: void;
    /** Fired when the channel transitions to "closed". Mirrors RTCDataChannel.close event. */
    close: void;
    /** Underlying-channel error. Distinct from `send()` rejection (which is per-call). */
    error: {
        err: Error;
    };
    /** Inbound payload. */
    message: {
        data: string | ArrayBuffer;
    };
}

interface RemotePeerEventMap {
    "state-change": {
        from: PeerConnectionState;
        to: PeerConnectionState;
    };
    /**
     * SDP negotiation flow (createOffer / createAnswer /
     * setRemoteDescription) threw. Usually transient — negotiation
     * recovers on the next exchange and no action is needed.
     *
     * The one terminal case is `err.name === "IceRestartExhaustedError"`:
     * the SDK's automatic ICE-restart budget for this peer is spent and
     * the connection will not recover on its own. Branch on `err.name`
     * (message strings are not a stable contract) and recover by closing
     * and re-joining, or by prompting the user.
     */
    "negotiation-error": {
        err: Error;
    };
    /** Inbound remote ICE candidate rejected by addIceCandidate (usually benign stale candidate). */
    "ice-candidate-error": {
        err: Error;
    };
    /**
     * Remote added a track. Customer code attaches to MediaElement.
     *
     * `metadata` is populated if the sender stamped per-track metadata
     * via `peer.addTrack(t, s, meta)` / `peer.addStream(s, meta)`. The
     * metadata arrives via a separate signalling message ordered BEFORE
     * the SDP offer that delivers the track, so it's stashed by the
     * time this event fires.
     */
    track: {
        track: MediaStreamTrack;
        streams: ReadonlyArray<MediaStream>;
        metadata?: StreamMetadata;
    };
    /** Remote opened a DataChannel. */
    "data-channel": {
        channel: RTCDataChannel;
    };
    /**
     * Fires the first time a previously-unseen MediaStream id appears
     * on this peer. Symmetric with the sender's `addStream(stream, meta)`.
     *
     * For uniform-metadata streams (the addStream path), `metadata` is
     * the metadata the sender passed. For mixed-metadata streams (the
     * advanced addTrack-per-track path), `metadata` is whatever the
     * FIRST track received carried — for per-track precision use the
     * per-track `metadata` field on the `track` event.
     *
     * Re-fires after a transient WS drop + reconcile: the remote sender
     * is the same RemotePeer, but the underlying PC was swapped, so the
     * new PC's track events surface fresh MediaStream objects with the
     * same `stream.id` as before. Customers binding `<video>.srcObject =
     * stream` should re-bind on each `stream-added`.
     */
    "stream-added": {
        stream: MediaStream;
        metadata?: StreamMetadata;
    };
    /**
     * Fires when a previously-seen MediaStream has no live tracks left
     * at this receiver — the sender removed them (`removeStream(stream)`
     * or the final `removeTrack(track)` of the stream), or every track
     * ended. Detection covers both signals real browsers emit: the
     * stream's `removetrack` (sender-side removal) and the track's
     * `ended` (stopped transceiver / closed connection).
     *
     * NOT fired during reconcile (PC swap closes old tracks but the
     * RemotePeer suppresses stream-removed for those — the customer
     * sees a fresh `stream-added` on the new PC instead).
     */
    "stream-removed": {
        stream: MediaStream;
    };
    /**
     * The SDK re-established the underlying connection to this peer
     * after a transient signalling drop. By the time the handler runs,
     * `remote.pc` already points at the fresh connection.
     *
     * Anything your app created on the previous connection is gone —
     * most importantly data channels opened via
     * `remote.pc.createDataChannel(...)`: re-create them here. (Tracks
     * added via `peer.addStream` / `peer.addTrack` are re-attached
     * automatically, and incoming media re-announces via
     * `stream-added`.)
     *
     * Does NOT fire for the initial connection — use `peer-joined`
     * for first-time setup. For apps with no media (data-channel-only),
     * this is the only reliable re-create signal: without tracks there
     * is no negotiation to drive `state-change` back to `"connected"`
     * until the app itself creates a channel on the new connection.
     */
    "connection-reset": Record<string, never>;
}
declare class RemotePeer extends EventEmitter<RemotePeerEventMap> {
    #private;
    readonly id: string;
    /**
     * Metadata the remote stamped on the connection (server-side
     * `peerMetadata` JWT claim, surfaced here as `metadata`). Treat
     * as untrusted: any peer in the channel can publish whatever shape
     * they want under this slot.
     *
     * Marked `readonly` for customer-side immutability (you cannot
     * write to it), but the SDK may refresh it during reconcile if the
     * remote rotated its JWT during a transient WS drop. Customers
     * reading `remote.metadata.displayName` after a `state-change` to
     * `"connected"` post-reconcile may see updated values; no event
     * fires for the refresh (poll on read if you need to react).
     */
    readonly metadata?: Record<string, unknown>;
    constructor(init: RemotePeerInit);
    get state(): PeerConnectionState;
    /** Perfect-negotiation politeness flag. Exposed for introspection / tests. */
    get polite(): boolean;
    /**
     * Escape hatch — the underlying RTCPeerConnectionLike. For advanced
     * callers needing `getStats()`, custom event listeners, or other
     * low-level access. NOTE: mutating its configuration via
     * `setConfiguration()` bypasses MeteredPeer's iceServer validation;
     * only do that if you really need to.
     */
    get pc(): RTCPeerConnectionLike;
    /**
     * Send `data` directly to this peer (server-routed via the
     * signalling channel's `send` frame). Rejects with the underlying
     * error if the signalling socket isn't connected or the server
     * rejects the request. Shorthand for `peer.send(remote.id, data)`.
     *
     * After `_close()`, this rejects with "RemotePeer is closed" so
     * a stale ref held by customer code can't ship frames at a
     * potentially-reused peerId.
     */
    send(data: unknown): Promise<void>;
    /**
     * Toggle JSON.stringify-safety. The default toJSON on EventEmitter
     * would still expose nothing useful, but pinning this here makes
     * the intent loud and means a future refactor can't accidentally
     * leak the connection / sendImpl bag.
     */
    toJSON(): {
        id: string;
        state: PeerConnectionState;
    };
}

type MeteredPeerState = "idle" | "joining" | "joined" | "reconnecting" | "leaving" | "closed";
/**
 * Per-track metadata bag. The sender stamps it at addStream / addTrack
 * time; the SDK propagates it to every connected peer (and every
 * future newcomer / reconcile survivor) via a reserved-key direct
 * message. The receiver surfaces it on the `track` event payload and
 * (for the first track of each stream) on the `stream-added` event.
 *
 * Convention only — the SDK doesn't validate `role` / `label`. Use any
 * keys your app needs; remember that this is server-routed customer
 * payload and counts against the per-message size cap.
 */
interface StreamMetadata {
    /** Conventional role hint: "camera" | "screen" | "canvas" | "file" | custom. */
    role?: string;
    /** Human-readable label, e.g. "front cam", "shared screen". */
    label?: string;
    /** Customer-defined fields. */
    [key: string]: unknown;
}
/**
 * Thrown by `send()` when the JSON-serialized payload would exceed
 * the server's per-message cap. Typed so customers can branch on
 * `instanceof MeteredPeerOversizedError` without parsing message
 * strings.
 */
declare class MeteredPeerOversizedError extends Error {
    readonly name = "MeteredPeerOversizedError";
    readonly size: number;
    readonly cap: number;
    constructor(size: number, cap: number);
}
/**
 * Thrown by `send()` when the channel name uses a server-reserved
 * prefix or when the SDK isn't in a state that can accept sends
 * (not currently joined).
 */
declare class MeteredPeerSendError extends Error {
    readonly name = "MeteredPeerSendError";
    readonly code: "reserved_channel" | "not_joined" | "invalid_args" | "self_send";
    constructor(code: MeteredPeerSendError["code"], message: string);
}
/**
 * Thrown by `replaceTrack()` when ANY peer's underlying replaceTrack
 * rejects. Carries per-peer success / failure so customers can
 * converge surgically rather than guessing which side of the
 * fanout completed.
 *
 * Why a typed error and not just a single rejected promise: the
 * underlying `Promise.allSettled` fanout means a partial failure
 * leaves the channel in a split state — peers 1, 2, 4 on newTrack,
 * peer 3 still on oldTrack. Without the failed/succeeded lists,
 * the customer's natural retry (`removeStream` + `addStream`) can't
 * reconcile because `detachStream` matches by `sender.track === track`
 * and already-replaced peers won't match. With the lists, the
 * customer can call replaceTrack(newTrack, oldTrack) on just the
 * failed subset (or removeTrack from PC + addStream the new track)
 * without disturbing the already-replaced peers.
 */
/**
 * Thrown synchronously by methods that can't safely act in the
 * current `MeteredPeer.state` — `join`, `addStream`, `addTrack`,
 * `removeStream`, `removeTrack`, `replaceTrack`. Typed so customers
 * can branch via `instanceof` / `e.code` instead of parsing message
 * strings (which the SDK doesn't promise to keep stable).
 *
 * Codes:
 *   - `invalid_state` — generic "wrong state for this call". The
 *     `method` and `currentState` fields tell you which.
 *   - `track_already_attached` — addTrack/addStream called for a
 *     track already in the SDK's tracking map with a different
 *     stream association. Multi-stream membership (one track shared
 *     across multiple MediaStreams) is not currently supported; the
 *     SDK rejects loudly instead of silently dropping the second
 *     association.
 */
declare class MeteredPeerStateError extends Error {
    readonly name = "MeteredPeerStateError";
    readonly code: "invalid_state" | "track_already_attached";
    readonly method: string;
    readonly currentState?: string;
    constructor(code: MeteredPeerStateError["code"], method: string, message: string, currentState?: string);
}
declare class MeteredPeerReplaceTrackError extends Error {
    readonly name = "MeteredPeerReplaceTrackError";
    readonly succeeded: readonly string[];
    readonly failed: ReadonlyArray<{
        peerId: string;
        err: Error;
    }>;
    constructor(succeeded: readonly string[], failed: ReadonlyArray<{
        peerId: string;
        err: Error;
    }>);
}
interface MeteredPeerOptions extends SignallingClientOptions {
    /**
     * Test-injection point for RTCPeerConnection. Forwarded to every
     * PeerConnection MeteredPeer constructs. Production: omit — the
     * SDK uses globalThis.RTCPeerConnection (browsers) or whatever
     * the customer wired up via the same factory at SignallingClient
     * level.
     */
    rtcPeerConnectionFactory?: (config: RTCConfiguration) => RTCPeerConnectionLike;
}
interface JoinOptions {
    /**
     * Passthrough to SignallingClient.subscribe — when true, the server
     * stamps fromMetadata on broadcast messages we receive (the JWT
     * peerMetadata of the publisher).
     */
    includeSenderMetadata?: boolean;
}
interface MeteredPeerEventMap {
    /** Local peer entered the channel; peerId + channel are stable. */
    joined: {
        peerId: string;
        channel: string;
    };
    /**
     * Local peer fully disconnected (state === "closed"). Carries the
     * peerId + channel of the just-left session so customers writing
     * teardown logic don't have to stash them earlier. `peerId` /
     * `channel` may be `null` for peers that closed before a successful
     * join (the welcome / subscribe-ack never landed); `reason` carries
     * either the customer's argument to close() or the underlying close
     * code's message.
     */
    left: {
        peerId: string | null;
        channel: string | null;
        reason?: string;
    };
    /** Lifecycle state transition. */
    "state-change": {
        from: MeteredPeerState;
        to: MeteredPeerState;
    };
    /** Another peer subscribed to our channel. */
    "peer-joined": {
        peer: RemotePeer;
    };
    /** Another peer unsubscribed (or their connection dropped). */
    "peer-left": {
        peer: RemotePeer;
    };
    /**
     * Customer payload arrived from another peer. RTC signals
     * (`rtc-description`, `rtc-ice`) are NEVER surfaced here — they're
     * routed into the WebRTC layer.
     *
     * `senderPeerId` is the server-stamped envelope-level sender. The
     * naming is intentionally distinct from any `from` field a customer
     * might put inside their `data` payload — customers reading
     * `ev.data.from` instead of `ev.senderPeerId` would get whatever
     * the sender chose to put there (the SDK can't authenticate inner
     * fields).
     *
     * `kind` distinguishes channel broadcasts (one-to-many via
     * `peer.send(data)`) from server-routed direct messages (one-to-one
     * via `peer.sendTo(peerId, data)` or `remote.send(data)`). Both
     * land in this single `data` event so customers wiring up one
     * handler see all traffic; branch on `kind` when behavior must
     * differ.
     *
     * `senderMetadata` is the sender's JWT-signed `peerMetadata` claim,
     * populated only if the customer joined with
     * `JoinOptions.includeSenderMetadata: true`. The server stamps it
     * onto outbound messages from this peer to subscribers, so unlike
     * `remote.metadata` it's available on every inbound payload without
     * needing a corresponding `peer-joined` event (useful for
     * cross-channel-style apps where the publisher isn't necessarily a
     * `RemotePeer` you've seen). The shape is whatever the publisher
     * stamped in their JWT — treat as untrusted user input.
     */
    data: {
        senderPeerId: string;
        data: unknown;
        kind: "broadcast" | "direct";
        senderMetadata?: Record<string, unknown>;
    };
    /** Unrecoverable error — typically a thrown handler. */
    error: {
        err: Error;
    };
}
declare class MeteredPeer extends EventEmitter<MeteredPeerEventMap> {
    #private;
    private readonly client;
    private _state;
    private _localPeerId;
    private _channel;
    private _iceServers;
    private _maxMessageSize;
    private readonly peers;
    constructor(opts: MeteredPeerOptions);
    /**
     * toJSON override. Prevents accidental credential leak when a
     * customer's logging / observability tooling stringifies the peer
     * (Sentry breadcrumbs, console.dir, JSON.stringify). The ES-private
     * #opts already makes this technically safe; pinning toJSON here
     * documents the intent explicitly and survives field refactors.
     */
    toJSON(): {
        state: MeteredPeerState;
        peerId: string | null;
        channel: string | null;
    };
    get state(): MeteredPeerState;
    /** Stable peerId assigned by the server at first welcome. */
    get peerId(): string | null;
    /** The channel currently joined, or null. */
    get channel(): string | null;
    /** Snapshot of currently-connected remote peers. */
    get remotePeers(): RemotePeer[];
    /**
     * Broadcast `data` to every peer in the channel via the
     * signalling-server's `publish` frame. The local peer's own send
     * is NOT echoed back to its own `data` event listener.
     *
     * Rejects if not currently joined or the server rejects the publish
     * (e.g., `over_message_quota`). For per-peer direct messaging use
     * `sendTo(peerId, data)`.
     */
    send(data: unknown): Promise<void>;
    /**
     * Send `data` directly to a single peer via the signalling-server's
     * `send` frame (server-routed, not WebRTC P2P). Use this for
     * lightweight messages without setting up a DataChannel.
     *
     * Rejects with a typed `MeteredPeerSendError` for `not_joined`,
     * `invalid_args`, or `self_send`; with `MeteredPeerOversizedError`
     * if the payload exceeds the server cap; or with the underlying
     * server error for missing peers / quota / authorization.
     */
    sendTo(peerId: string, data: unknown): Promise<void>;
    /**
     * Pre-compute the JSON-serialised byte length of an outbound
     * payload and reject if it would exceed the welcome-advertised cap.
     * Cheaper than waiting for the server to close the socket with
     * code 1009. Returns null on success.
     *
     * utf8ByteLength measures the serialized payload without requiring a
     * global TextEncoder, so the check works on runtimes that lack one
     * (some React Native / Hermes versions). Shared with the DataChannel
     * wrapper.
     */
    private checkPayloadSize;
    /**
     * Attach every track in `stream` to every current and future
     * RemotePeer. Sugar over `addTrack(t, stream, metadata)` per track.
     *
     * `metadata`, if provided, is stamped on EACH of the stream's tracks
     * (a fresh copy per track to avoid customer-side aliasing). The
     * receiver surfaces it on the `track` event and on `stream-added`
     * (which fires when the stream's id first appears at the remote).
     *
     * Tracks are tracked on this MeteredPeer so peers joining AFTER this
     * call also receive them. Calling addStream with the same stream
     * twice is idempotent — already-tracked tracks are skipped.
     *
     * Throws if the peer is in a terminal state (`leaving` / `closed`).
     * During `reconnecting`, tracks are added to the tracking map but
     * not fanned out to the in-flight (about-to-be-discarded) connections;
     * once the connection recovers, every tracked stream is automatically
     * re-attached to each surviving peer's new connection.
     */
    addStream(stream: MediaStream, metadata?: StreamMetadata): void;
    /**
     * Remove `stream` from every current peer and stop tracking its
     * tracks for future joins. Sugar over `removeTrack(track)` per track.
     *
     * No-op for tracks that were never added. Throws in terminal states
     * (`leaving` / `closed`). During `reconnecting`, tracks are removed
     * from the tracking map but no detach fires — the about-to-be-
     * replaced PCs will be discarded anyway.
     */
    removeStream(stream: MediaStream): void;
    /**
     * Attach a single track to every current and future RemotePeer. The
     * lower-level primitive that addStream sugars over.
     *
     * Pass `stream` to associate the track with a MediaStream on the
     * wire — the receiver sees that stream in the track event's `streams`
     * array, and (the first time the stream id appears) fires a
     * `stream-added` event. Omit `stream` for an unaffiliated track —
     * the receiver gets `streams: []` on the track event and no
     * `stream-added`.
     *
     * `metadata`, if provided, is propagated to every connected peer via
     * a reserved-key signalling message BEFORE the SDP offer goes out,
     * so the metadata lands at the receiver before the track event
     * fires. Survivors on reconcile get the metadata re-sent during the
     * PC swap; newcomers get it during their initial addTrack fanout.
     *
     * Idempotent on the same `track` reference — calling addTrack twice
     * with the same track is a no-op (metadata + stream from the FIRST
     * call wins; subsequent ones are dropped). To change metadata for an
     * already-tracked track, call `removeTrack(t)` then `addTrack(t, ...)`
     * with the new values.
     *
     * Throws in terminal states (`leaving` / `closed`). During
     * `reconnecting`, the track is added to the tracking map but not
     * fanned out; once the connection recovers, every tracked track is
     * automatically re-attached to each surviving peer's new connection
     * (its metadata is re-sent before the track so ordering is preserved
     * relative to the SDP offer).
     */
    addTrack(track: MediaStreamTrack, stream?: MediaStream, metadata?: StreamMetadata): void;
    /**
     * Remove a single track from every current peer and stop tracking it
     * for future joins. Counterpart to addTrack.
     *
     * No-op if `track` was never added. Throws in terminal states
     * (`leaving` / `closed`). During `reconnecting`, the track is
     * removed from the tracking map but no detach fires.
     */
    removeTrack(track: MediaStreamTrack): void;
    /**
     * Look up the metadata the SDK is tracking for a sender-side track.
     * Returns undefined if `track` was never addTrack'd / addStream'd,
     * or if it was added without metadata.
     */
    getTrackMetadata(track: MediaStreamTrack): StreamMetadata | undefined;
    /**
     * Look up the metadata the SDK is tracking for a sender-side stream.
     * Sugar for `getTrackMetadata(stream.getTracks()[0])` — returns the
     * first track's metadata. For uniform-metadata streams (the addStream
     * path), this is the metadata the customer passed. For mixed-metadata
     * streams (advanced addTrack with different metas per track),
     * customers needing per-track precision should use getTrackMetadata
     * directly.
     *
     * Returns undefined if the stream has no tracks, no tracks of the
     * stream are tracked, or the first tracked one was added without
     * metadata.
     */
    getStreamMetadata(stream: MediaStream): StreamMetadata | undefined;
    /**
     * Swap `oldTrack` for `newTrack` (or null to silence) across every
     * RemotePeer where it's currently being sent. Doesn't trigger
     * renegotiation when codecs match — the whole point of replaceTrack.
     *
     * Resolves when every peer's replaceTrack has resolved. If ANY peer
     * rejects (typical cause: incompatible codec), throws a typed
     * `MeteredPeerReplaceTrackError` carrying per-peer succeeded /
     * failed lists. Customers can converge surgically:
     *
     *   try { await peer.replaceTrack(oldT, newT); }
     *   catch (e) {
     *     if (e instanceof MeteredPeerReplaceTrackError) {
     *       // peers in e.succeeded are on newT; e.failed are still on oldT.
     *       // retry only the failed subset, or rebuild via removeStream
     *       // + addStream targeted at e.failed peers.
     *     }
     *   }
     *
     * If 0 peers are connected, resolves trivially with no work done.
     */
    replaceTrack(oldTrack: MediaStreamTrack, newTrack: MediaStreamTrack | null): Promise<void>;
    /**
     * Connect to the signalling-server (if not connected) and subscribe
     * to `channel`. Resolves once the subscribe ack lands; peers are
     * discovered asynchronously via the server's `presence` event.
     *
     * Idempotent only in the success sense — re-joining the same channel
     * while already joined throws. To switch channels, construct a new
     * MeteredPeer (close() is terminal).
     */
    join(channel: string, opts?: JoinOptions): Promise<void>;
    /**
     * Close every remote peer connection, close the signalling socket,
     * and transition to "closed". Terminal — once close() has been
     * called, the MeteredPeer instance can't be reused; construct a new
     * one to rejoin. Idempotent.
     */
    close(reason?: string): Promise<void>;
    private onSignallingConnected;
    private onSignallingDisconnected;
    /**
     * Server-error events that customers need to see as fatal.
     *
     * Most server-errors are correlated to a pending request and come
     * back as Promise.reject from subscribe/publish/sendTo. Those
     * never reach this handler. The uncorrelated ones (server-initiated
     * rejections without a requestId — typically over_message_quota
     * mid-stream) DO surface here.
     *
     * Filter for codes the customer must react to (account suspended,
     * channel unauthorized, action not permitted on the joined channel).
     * Pure quota / rate-limit signals stay below the noise floor and
     * customers can read them off `server-error` directly if needed.
     */
    private onServerError;
    /**
     * Token provider has failed N consecutive reconnect attempts.
     * The SignallingClient's reconnect ladder keeps retrying internally,
     * but at this point the customer's auth pipeline is the bottleneck
     * — surface it to the customer-facing error channel so a UI can
     * prompt re-login.
     *
     * The threshold mirrors the default in SignallingClient's
     * token-provider-error event (3 consecutive failures); we don't
     * over-amplify by re-emitting on every retry.
     */
    private onTokenProviderError;
    private onPresence;
    /**
     * Reconcile: diff the post-reconnect snapshot against
     * `this.peers`. Order of operations:
     *
     *   1. Build the snapshot ID set (deduped, self filtered)
     *   2. Process departures FIRST — peers no longer in the channel.
     *      Fires `peer-left` with the OLD RemotePeer for each.
     *   3. Process snapshot entries:
     *      - Existing  → silent PC swap inside the same RemotePeer
     *      - Missing   → addPeer (fires `peer-joined`)
     *   4. Transition back to "joined"
     *
     * Doing departures first keeps the peers map size monotonically
     * decreasing as we iterate, easier to reason about.
     */
    private reconcileFromSnapshot;
    /**
     * Silent PC swap for a surviving RemotePeer. Builds a fresh
     * PeerConnection with the latest iceServers + signalling sender,
     * hands it to the RemotePeer (which detaches old listeners, closes
     * the old PC, and re-attaches to the new one), then re-attaches
     * every local stream from `#localStreams` so the new PC ships
     * the customer's media in its first SDP offer.
     *
     * Does NOT fire peer-left / peer-joined — the customer's ref to
     * `remote` is the same instance before and after this call.
     */
    private swapPeerConnection;
    private onDirect;
    private onMessage;
    private addPeer;
    private removePeer;
    /**
     * The signalling adapter passed into every PeerConnection. Wraps
     * SignallingClient.send so SDP / ICE signals route through the
     * server's `direct` channel to the target peer.
     */
    private readonly signallingSender;
    private setState;
}

/**
 * Thrown by `send()` when too many sends are queued behind the
 * backpressure wait. Without this cap, a customer's
 * `for(;;) dc.send(big)` on a stalled link would grow the JS heap
 * until OOM. The cap rejects past `maxQueuedSends` so the producer
 * sees a real signal to back off.
 *
 * Typed so customers can `instanceof DataChannelOverflowError` and
 * branch on it without parsing message strings.
 */
declare class DataChannelOverflowError extends Error {
    readonly name = "DataChannelOverflowError";
    readonly queued: number;
    readonly cap: number;
    constructor(queued: number, cap: number);
}
declare class DataChannel extends EventEmitter<DataChannelEventMap> {
    readonly label: string;
    private readonly channel;
    private readonly logger;
    private readonly maxBufferedAmount;
    private readonly maxQueuedSends;
    private sendChain;
    private queuedSendCount;
    private pendingLowWaiters;
    private closed;
    private readonly handlers;
    constructor(channel: RTCDataChannelLike, opts?: DataChannelOptions);
    get readyState(): RTCDataChannelState;
    get bufferedAmount(): number;
    /**
     * Queue a send. Resolves once the message has been handed to the
     * underlying channel. Rejects if the channel is not open. Each
     * queued send settles independently — one failed send does not
     * reject the sends queued behind it.
     *
     * Backpressure: if bufferedAmount would exceed maxBufferedAmount,
     * the call suspends until `bufferedamountlow` fires before calling
     * channel.send().
     *
     * Overflow guard: if more than `maxQueuedSends` are
     * already waiting in the chain, this rejects synchronously with a
     * typed `DataChannelOverflowError`. Without the cap, fire-and-
     * forget producers on a stalled link grow JS heap until OOM.
     */
    send(data: string | ArrayBuffer): Promise<void>;
    /** Close the underlying channel + detach listeners. Idempotent. */
    close(): void;
    private doSend;
    private waitForLowBuffer;
    private detachListeners;
    private onOpen;
    private onClose;
    private onError;
    private onMessage;
}

/**
 * The customer-supplied credential. EXACTLY one of `apiKey` or
 * `tokenProvider` is required.
 *
 *  - `apiKey`: a pk_live_ publishable key. Goes straight into the
 *    `?key=` query param on the WS upgrade. Browser-safe by design.
 *    Use this when the customer is happy with the per-key
 *    channelPatterns and actions configured at the dashboard.
 *
 *  - `tokenProvider`: an async function returning a JWT signed with
 *    the customer's sk_ secret. Called on first connect AND on every
 *    reconnect (so refreshed tokens land automatically). Use this
 *    when the customer wants per-user scoping that pk_ keys can't
 *    express (custom `channels`, `permissions`, `metadata` claims).
 */
type TokenProvider = () => Promise<string>;
interface SignallingClientOptions {
    /** Either `apiKey` OR `tokenProvider`. Not both. */
    apiKey?: string;
    tokenProvider?: TokenProvider;
    /**
     * Signalling-server URL. Defaults to "wss://rms.metered.ca".
     * Path is appended automatically — supply only the origin.
     *
     * Validated at construction:
     *   - protocol must be `wss:` (or `ws:` for localhost / 127.0.0.1)
     *   - no path / query / hash — peer-lib appends /v1 itself
     *
     * Invalid URLs throw TypeError immediately so misconfigs are
     * caught at integration time, not mid-connect.
     */
    url?: string;
    /**
     * How long to wait for `tokenProvider()` to resolve before treating
     * the call as a failure. Default 10_000 ms. Defends against a
     * hanging customer mint endpoint pinning `connect()` indefinitely.
     * Only applies to the tokenProvider path; apiKey is sync.
     *
     * Must be a finite number > 0 — anything else throws a TypeError at
     * construction. There is deliberately no disable value: a provider
     * with no timeout pins `connect()` forever on a hung mint endpoint,
     * which is the exact failure this option exists to prevent.
     */
    tokenProviderTimeoutMs?: number;
    /**
     * Customer-supplied logger. Defaults to a no-op. Pass console for
     * dev visibility or your structured-logging adapter for prod.
     */
    logger?: Logger;
    /**
     * Reconnection knobs. Defaults documented at ReconnectOptions.
     * Set `reconnect: false` to disable auto-reconnect entirely.
     */
    reconnect?: ReconnectOptions | false;
    /**
     * Liveness timeout in ms. The client closes-and-reconnects if no
     * frame arrives from the server within this window. Default 60_000.
     *
     * The SDK also sends a lightweight application-level keepalive at an
     * interval shorter than this window so an idle connection stays alive
     * automatically. Customers who tune this value get the keepalive
     * adjusted in lock-step.
     *
     * Set to `0` (or any non-positive / non-finite value) to disable
     * the watchdog — the keepalive is disabled with it, matching the
     * other Metered Realtime SDKs. `NaN` throws a TypeError at
     * construction.
     */
    inactivityTimeoutMs?: number;
    /**
     * When true (default), the client re-issues subscribe frames for
     * every channel the customer was subscribed to before a drop, on
     * each successful reconnect. Without this, customers who don't
     * wire up a `connected` listener silently lose subscriptions on
     * the first reconnect and `messages mysteriously stop arriving`.
     *
     * Set to `false` if you want per-session subscription scoping
     * (e.g. UI components that subscribe on mount + want to start
     * over after a reconnect).
     */
    autoResubscribe?: boolean;
    /**
     * Inject a WebSocket factory for tests. Production never needs this
     * — the client uses globalThis.WebSocket. The factory is called
     * with the fully-formed `wss://…/v1?token=…` URL.
     */
    webSocketFactory?: (url: string) => WebSocketLike;
}
interface ReconnectOptions {
    /** Initial backoff in ms. Default 500. */
    initialDelayMs?: number;
    /** Multiplier per attempt. Default 2. */
    multiplier?: number;
    /** Upper bound in ms. Default 30_000. */
    maxDelayMs?: number;
    /** ±jitter fraction. Default 0.2 (i.e. ±20% of the computed delay). */
    jitterRatio?: number;
    /**
     * Give up after this many consecutive failures. Default 100.
     *
     * With the default backoff (500 ms → 30 s cap, ×2 each), 100
     * attempts span roughly 50 minutes. After exhaustion the client
     * transitions to `closed` and emits a final `disconnected` event;
     * the customer's app code must call `connect()` again to resume.
     *
     * Set to `Infinity` to retry forever — useful for daemon-style
     * indefinite reconnect against a long-flaky link.
     */
    maxAttempts?: number;
}

type LogLevel = "debug" | "info" | "warn" | "error";
interface Logger {
    debug(msg: string, ctx?: Record<string, unknown>): void;
    info(msg: string, ctx?: Record<string, unknown>): void;
    warn(msg: string, ctx?: Record<string, unknown>): void;
    error(msg: string, ctx?: Record<string, unknown>): void;
}

/**
 * Client lifecycle state. Reflects the union of "what the SDK thinks
 * the connection is doing right now". Surface via `client.state`
 * and the `state-change` event.
 */
type SignallingClientState = "idle" | "connecting" | "connected" | "reconnecting" | "closed";
/**
 * Events emitted by SignallingClient. Subscribe via `.on(event, cb)`,
 * unsubscribe via `.off(event, cb)`. One-shot via `.once(event, cb)`.
 */
interface SignallingClientEventMap {
    /**
     * Fired after the welcome frame is received and the connection is
     * ready. `isReconnect: true` distinguishes a reconnect-success
     * from the initial connect — useful for "show 'reconnected' toast"
     * UI without false-firing it on first connect.
     */
    connected: {
        peerId: string;
        serverTime: number;
        expiresAt: number | null;
        isReconnect: boolean;
        /**
         * Server-advertised cap on outbound payload size in bytes. The
         * SDK uses this to reject oversized sends client-side with a
         * typed error (`OversizedPayloadError` from SignallingClient's
         * `publish()` / `send()`; `MeteredPeerOversizedError` from
         * MeteredPeer's) rather than letting the server close the socket
         * with code 1009.
         */
        maxMessageSize: number;
        /**
         * TURN credentials from the welcome's `iceServers` field, if any.
         * MeteredPeer auto-applies these to outbound peer
         * connections; consumers using the SignallingClient directly can
         * read them off this event and pass to RTCPeerConnection's
         * configuration manually.
         */
        iceServers?: IceServerConfig[];
    };
    /** Fired once the underlying socket is fully closed. */
    disconnected: {
        code: number;
        reason: string;
        willReconnect: boolean;
    };
    /** Fired when the client transitions between lifecycle states. */
    "state-change": {
        from: SignallingClientState;
        to: SignallingClientState;
    };
    /** Inbound channel publish — what the server calls `message`. */
    message: MessageEvent;
    /** Inbound direct (point-to-point) message. */
    direct: DirectMessageEvent;
    /** Channel presence join / leave. */
    presence: PresenceEvent;
    /**
     * Server-sent protocol or quota error — a request the server
     * rejected (over-quota, malformed, unauthorized channel), surfaced
     * outside the normal Promise.reject path because some server errors
     * are unsolicited (no requestId to correlate to a pending call).
     *
     * The payload is the wire-level error frame: `{ requestId?, code,
     * message? }`. Distinct from MeteredPeer's `error` event (which
     * carries `{ err: Error }` for JS-level exceptions).
     */
    "server-error": ServerErrorEvent;
    /** Server is shutting down gracefully. Surface to UI as "reconnecting…" */
    "going-away": GoingAwayEvent;
    /**
     * Fired when the customer's `tokenProvider` has failed for N
     * consecutive reconnect attempts (default 3). Surface as an
     * actionable user-facing UI ("your auth is failing — please log
     * in again") rather than letting the client spin silently in
     * 'reconnecting' state forever. The client keeps retrying after
     * this fires; the event is informational.
     */
    "token-provider-error": {
        consecutiveFailures: number;
        err: Error;
    };
}
/**
 * Browser WebSocket client speaking the Metered Realtime Messaging
 * wire protocol.
 *
 * Usage (pk_ key path):
 *   const client = new SignallingClient({ apiKey: "pk_live_..." });
 *   await client.connect();
 *   client.on("message", ({ channel, from, data }) => { ... });
 *   await client.subscribe("room-42");
 *   await client.publish("room-42", { hello: "world" });
 *
 * Usage (sk_ JWT path):
 *   const client = new SignallingClient({
 *     tokenProvider: async () => {
 *       const r = await fetch("/api/mint-signalling-token");
 *       const { token } = await r.json();
 *       return token;
 *     },
 *   });
 *   await client.connect();
 *
 * Connection lifecycle:
 *   - connect() resolves after the welcome frame arrives
 *   - close() is terminal — no auto-reconnect after explicit close
 *   - Auto-reconnect on transient drops is built-in (see ReconnectOptions)
 */
declare class SignallingClient {
    private readonly _impl;
    constructor(opts: SignallingClientOptions);
    get state(): SignallingClientState;
    connect(): Promise<void>;
    close(code?: number, reason?: string): Promise<void>;
    subscribe(channel: string, opts?: SubscribeOptions): Promise<void>;
    unsubscribe(channel: string): Promise<void>;
    publish(channel: string, data: unknown, opts?: PublishOptions): Promise<void>;
    send(toPeerId: string, data: unknown, opts?: SendOptions): Promise<void>;
    on<K extends keyof SignallingClientEventMap>(event: K, handler: (payload: SignallingClientEventMap[K]) => void): this;
    off<K extends keyof SignallingClientEventMap>(event: K, handler: (payload: SignallingClientEventMap[K]) => void): this;
    once<K extends keyof SignallingClientEventMap>(event: K, handler: (payload: SignallingClientEventMap[K]) => void): this;
}
/**
 * Subset of the WebSocket interface peer-lib relies on. Customers can
 * pass a fake via `webSocketFactory` for tests. Mirrors the browser
 * `WebSocket` so a real one passes the type check by structural
 * compatibility.
 */
interface WebSocketLike {
    readyState: number;
    send(data: string): void;
    close(code?: number, reason?: string): void;
    addEventListener(type: "open" | "close" | "message" | "error", listener: (ev: unknown) => void): void;
    removeEventListener(type: "open" | "close" | "message" | "error", listener: (ev: unknown) => void): void;
}

export { ConsoleLogger, DataChannel, DataChannelOverflowError, MeteredPeer, MeteredPeerOversizedError, MeteredPeerReplaceTrackError, MeteredPeerSendError, MeteredPeerStateError, NoopLogger, OversizedPayloadError, RemotePeer, SignallingClient, SignallingConnectError, WsCloseCode, WsCloseCode as WsCloseCodeValue };
export type { MessageEvent as ChannelMessage, DataChannelEventMap, DataChannelOptions, DirectMessageEvent, ErrorCode, GoingAwayEvent, IceServerConfig, JoinOptions, LogLevel, Logger, MeteredPeerEventMap, MeteredPeerOptions, MeteredPeerState, PeerConnectionState, PresenceEvent, PresencePeer, PublishOptions, RTCPeerConnectionLike, ReconnectOptions, RemotePeerEventMap, SendOptions, ServerErrorEvent, SignallingClientEventMap, SignallingClientOptions, SignallingClientState, StreamMetadata, SubscribeOptions, TokenProvider, WebSocketLike, WelcomePayload };