@pulsebeam/peer 0.0.11 → 0.0.13

package/dist/index.d.ts

@@ -0,0 +1,668 @@
+import { RpcOptions, UnaryCall } from '@protobuf-ts/runtime-rpc';
+import { MessageType } from '@protobuf-ts/runtime';
+
+/**
+ * @generated from protobuf enum pulsebeam.v1.SdpKind
+ */
+declare enum SdpKind {
+    /**
+     * @generated from protobuf enum value: SDP_KIND_UNSPECIFIED = 0;
+     */
+    UNSPECIFIED = 0,
+    /**
+     * @generated from protobuf enum value: SDP_KIND_OFFER = 1;
+     */
+    OFFER = 1,
+    /**
+     * @generated from protobuf enum value: SDP_KIND_ANSWER = 2;
+     */
+    ANSWER = 2,
+    /**
+     * @generated from protobuf enum value: SDP_KIND_PRANSWER = 3;
+     */
+    PRANSWER = 3,
+    /**
+     * @generated from protobuf enum value: SDP_KIND_ROLLBACK = 4;
+     */
+    ROLLBACK = 4
+}
+declare class PrepareReq$Type extends MessageType<PrepareReq> {
+    constructor();
+}
+/**
+ * @generated from protobuf message pulsebeam.v1.PrepareReq
+ */
+interface PrepareReq {
+}
+/**
+ * @generated MessageType for protobuf message pulsebeam.v1.PrepareReq
+ */
+declare const PrepareReq: PrepareReq$Type;
+declare class PrepareResp$Type extends MessageType<PrepareResp> {
+    constructor();
+}
+/**
+ * @generated from protobuf message pulsebeam.v1.PrepareResp
+ */
+interface PrepareResp {
+    /**
+     * @generated from protobuf field: repeated pulsebeam.v1.IceServer ice_servers = 1;
+     */
+    iceServers: IceServer[];
+}
+/**
+ * @generated MessageType for protobuf message pulsebeam.v1.PrepareResp
+ */
+declare const PrepareResp: PrepareResp$Type;
+declare class IceServer$Type extends MessageType<IceServer> {
+    constructor();
+}
+/**
+ * @generated from protobuf message pulsebeam.v1.IceServer
+ */
+interface IceServer {
+    /**
+     * @generated from protobuf field: repeated string urls = 1;
+     */
+    urls: string[];
+    /**
+     * @generated from protobuf field: optional string username = 2;
+     */
+    username?: string;
+    /**
+     * @generated from protobuf field: optional string credential = 3;
+     */
+    credential?: string;
+}
+/**
+ * @generated MessageType for protobuf message pulsebeam.v1.IceServer
+ */
+declare const IceServer: IceServer$Type;
+declare class SendReq$Type extends MessageType<SendReq> {
+    constructor();
+}
+/**
+ * @generated from protobuf message pulsebeam.v1.SendReq
+ */
+interface SendReq {
+    /**
+     * @generated from protobuf field: pulsebeam.v1.Message msg = 1;
+     */
+    msg?: Message;
+}
+/**
+ * @generated MessageType for protobuf message pulsebeam.v1.SendReq
+ */
+declare const SendReq: SendReq$Type;
+declare class SendResp$Type extends MessageType<SendResp> {
+    constructor();
+}
+/**
+ * @generated from protobuf message pulsebeam.v1.SendResp
+ */
+interface SendResp {
+}
+/**
+ * @generated MessageType for protobuf message pulsebeam.v1.SendResp
+ */
+declare const SendResp: SendResp$Type;
+declare class RecvReq$Type extends MessageType<RecvReq> {
+    constructor();
+}
+/**
+ * @generated from protobuf message pulsebeam.v1.RecvReq
+ */
+interface RecvReq {
+    /**
+     * @generated from protobuf field: pulsebeam.v1.PeerInfo info = 1;
+     */
+    info?: PeerInfo;
+}
+/**
+ * @generated MessageType for protobuf message pulsebeam.v1.RecvReq
+ */
+declare const RecvReq: RecvReq$Type;
+declare class RecvResp$Type extends MessageType<RecvResp> {
+    constructor();
+}
+/**
+ * @generated from protobuf message pulsebeam.v1.RecvResp
+ */
+interface RecvResp {
+    /**
+     * @generated from protobuf field: repeated pulsebeam.v1.Message msgs = 1;
+     */
+    msgs: Message[];
+}
+/**
+ * @generated MessageType for protobuf message pulsebeam.v1.RecvResp
+ */
+declare const RecvResp: RecvResp$Type;
+declare class PeerInfo$Type extends MessageType<PeerInfo> {
+    constructor();
+}
+/**
+ * @generated from protobuf message pulsebeam.v1.PeerInfo
+ */
+interface PeerInfo {
+    /**
+     * @generated from protobuf field: uint32 conn_id = 1;
+     */
+    connId: number;
+    /**
+     * @generated from protobuf field: bool enable_discovery = 2;
+     */
+    enableDiscovery: boolean;
+}
+/**
+ * @generated MessageType for protobuf message pulsebeam.v1.PeerInfo
+ */
+declare const PeerInfo: PeerInfo$Type;
+declare class Message$Type extends MessageType<Message> {
+    constructor();
+}
+/**
+ * Use small tag numbers (1-15) for fields that are frequently used or are performance-sensitive, even if they are optional.
+ * Larger tag numbers (16 and above) can be used for fields that are optional and not frequently included in messages, as they will require more bytes to encode.
+ * Avoid the 19000–19999 range, as it's reserved.
+ * Consider future-proofing your schema by leaving gaps between field numbers to allow for extensions or new fields later.
+ *
+ * @generated from protobuf message pulsebeam.v1.Message
+ */
+interface Message {
+    /**
+     * @generated from protobuf field: pulsebeam.v1.MessageHeader header = 1;
+     */
+    header?: MessageHeader;
+    /**
+     * payload will be treated as opaque in backend. Size limit is 10kB.
+     *
+     * @generated from protobuf field: pulsebeam.v1.MessagePayload payload = 2;
+     */
+    payload?: MessagePayload;
+}
+/**
+ * @generated MessageType for protobuf message pulsebeam.v1.Message
+ */
+declare const Message: Message$Type;
+declare class MessagePayload$Type extends MessageType<MessagePayload> {
+    constructor();
+}
+/**
+ * @generated from protobuf message pulsebeam.v1.MessagePayload
+ */
+interface MessagePayload {
+    /**
+     * @generated from protobuf oneof: payload_type
+     */
+    payloadType: {
+        oneofKind: "signal";
+        /**
+         * @generated from protobuf field: pulsebeam.v1.Signal signal = 1;
+         */
+        signal: Signal;
+    } | {
+        oneofKind: "join";
+        /**
+         * @generated from protobuf field: pulsebeam.v1.Join join = 2;
+         */
+        join: Join;
+    } | {
+        oneofKind: "bye";
+        /**
+         * @generated from protobuf field: pulsebeam.v1.Bye bye = 3;
+         */
+        bye: Bye;
+    } | {
+        oneofKind: "ack";
+        /**
+         * @generated from protobuf field: pulsebeam.v1.Ack ack = 4;
+         */
+        ack: Ack;
+    } | {
+        oneofKind: undefined;
+    };
+}
+/**
+ * @generated MessageType for protobuf message pulsebeam.v1.MessagePayload
+ */
+declare const MessagePayload: MessagePayload$Type;
+declare class MessageHeader$Type extends MessageType<MessageHeader> {
+    constructor();
+}
+/**
+ * @generated from protobuf message pulsebeam.v1.MessageHeader
+ */
+interface MessageHeader {
+    /**
+     * @generated from protobuf field: string group_id = 1;
+     */
+    groupId: string;
+    /**
+     * @generated from protobuf field: string peer_id = 2;
+     */
+    peerId: string;
+    /**
+     * @generated from protobuf field: uint32 conn_id = 3;
+     */
+    connId: number;
+    /**
+     * @generated from protobuf field: string other_group_id = 4;
+     */
+    otherGroupId: string;
+    /**
+     * @generated from protobuf field: string other_peer_id = 5;
+     */
+    otherPeerId: string;
+    /**
+     * @generated from protobuf field: uint32 other_conn_id = 6;
+     */
+    otherConnId: number;
+    /**
+     * @generated from protobuf field: uint32 seqnum = 7;
+     */
+    seqnum: number;
+    /**
+     * @generated from protobuf field: bool reliable = 8;
+     */
+    reliable: boolean;
+}
+/**
+ * @generated MessageType for protobuf message pulsebeam.v1.MessageHeader
+ */
+declare const MessageHeader: MessageHeader$Type;
+declare class Signal$Type extends MessageType<Signal> {
+    constructor();
+}
+/**
+ * @generated from protobuf message pulsebeam.v1.Signal
+ */
+interface Signal {
+    /**
+     * @generated from protobuf field: uint32 generation_counter = 1;
+     */
+    generationCounter: number;
+    /**
+     * @generated from protobuf oneof: data
+     */
+    data: {
+        oneofKind: "sdp";
+        /**
+         * @generated from protobuf field: pulsebeam.v1.Sdp sdp = 9;
+         */
+        sdp: Sdp;
+    } | {
+        oneofKind: "iceCandidate";
+        /**
+         * @generated from protobuf field: pulsebeam.v1.ICECandidate ice_candidate = 10;
+         */
+        iceCandidate: ICECandidate;
+    } | {
+        oneofKind: undefined;
+    };
+}
+/**
+ * @generated MessageType for protobuf message pulsebeam.v1.Signal
+ */
+declare const Signal: Signal$Type;
+declare class Sdp$Type extends MessageType<Sdp> {
+    constructor();
+}
+/**
+ * @generated from protobuf message pulsebeam.v1.Sdp
+ */
+interface Sdp {
+    /**
+     * @generated from protobuf field: pulsebeam.v1.SdpKind kind = 1;
+     */
+    kind: SdpKind;
+    /**
+     * @generated from protobuf field: string sdp = 2;
+     */
+    sdp: string;
+}
+/**
+ * @generated MessageType for protobuf message pulsebeam.v1.Sdp
+ */
+declare const Sdp: Sdp$Type;
+declare class ICECandidate$Type extends MessageType<ICECandidate> {
+    constructor();
+}
+/**
+ * @generated from protobuf message pulsebeam.v1.ICECandidate
+ */
+interface ICECandidate {
+    /**
+     * @generated from protobuf field: string candidate = 1;
+     */
+    candidate: string;
+    /**
+     * @generated from protobuf field: optional uint32 sdp_m_line_index = 2;
+     */
+    sdpMLineIndex?: number;
+    /**
+     * @generated from protobuf field: optional string sdp_mid = 3;
+     */
+    sdpMid?: string;
+    /**
+     * @generated from protobuf field: optional string username = 4;
+     */
+    username?: string;
+    /**
+     * @generated from protobuf field: optional string password = 5;
+     */
+    password?: string;
+}
+/**
+ * @generated MessageType for protobuf message pulsebeam.v1.ICECandidate
+ */
+declare const ICECandidate: ICECandidate$Type;
+declare class Join$Type extends MessageType<Join> {
+    constructor();
+}
+/**
+ * @generated from protobuf message pulsebeam.v1.Join
+ */
+interface Join {
+}
+/**
+ * @generated MessageType for protobuf message pulsebeam.v1.Join
+ */
+declare const Join: Join$Type;
+declare class Bye$Type extends MessageType<Bye> {
+    constructor();
+}
+/**
+ * @generated from protobuf message pulsebeam.v1.Bye
+ */
+interface Bye {
+}
+/**
+ * @generated MessageType for protobuf message pulsebeam.v1.Bye
+ */
+declare const Bye: Bye$Type;
+declare class Ack$Type extends MessageType<Ack> {
+    constructor();
+}
+/**
+ * @generated from protobuf message pulsebeam.v1.Ack
+ */
+interface Ack {
+    /**
+     * @generated from protobuf field: repeated pulsebeam.v1.AckRange ack_ranges = 1;
+     */
+    ackRanges: AckRange[];
+}
+/**
+ * @generated MessageType for protobuf message pulsebeam.v1.Ack
+ */
+declare const Ack: Ack$Type;
+declare class AckRange$Type extends MessageType<AckRange> {
+    constructor();
+}
+/**
+ * @generated from protobuf message pulsebeam.v1.AckRange
+ */
+interface AckRange {
+    /**
+     * @generated from protobuf field: uint32 seqnum_start = 1;
+     */
+    seqnumStart: number;
+    /**
+     * @generated from protobuf field: uint32 seqnum_end = 2;
+     */
+    seqnumEnd: number;
+}
+/**
+ * @generated MessageType for protobuf message pulsebeam.v1.AckRange
+ */
+declare const AckRange: AckRange$Type;
+
+/**
+ * @generated from protobuf service pulsebeam.v1.Tunnel
+ */
+interface ITunnelClient {
+    /**
+     * @generated from protobuf rpc: Prepare(pulsebeam.v1.PrepareReq) returns (pulsebeam.v1.PrepareResp);
+     */
+    prepare(input: PrepareReq, options?: RpcOptions): UnaryCall<PrepareReq, PrepareResp>;
+    /**
+     * @generated from protobuf rpc: Send(pulsebeam.v1.SendReq) returns (pulsebeam.v1.SendResp);
+     */
+    send(input: SendReq, options?: RpcOptions): UnaryCall<SendReq, SendResp>;
+    /**
+     * @generated from protobuf rpc: Recv(pulsebeam.v1.RecvReq) returns (pulsebeam.v1.RecvResp);
+     */
+    recv(input: RecvReq, options?: RpcOptions): UnaryCall<RecvReq, RecvResp>;
+}
+
+type LogObj = Record<string, unknown>;
+type LogHandler = (_obj: LogObj) => void;
+type LogSink = {
+    "DEBUG": LogHandler;
+    "INFO": LogHandler;
+    "WARN": LogHandler;
+    "ERROR": LogHandler;
+};
+declare class Logger {
+    readonly name: string;
+    private readonly obj;
+    private readonly sink;
+    constructor(name: string, obj?: LogObj, sink?: LogSink);
+    private log;
+    debug(message: string, obj?: LogObj): void;
+    info(message: string, obj?: LogObj): void;
+    warn(message: string, obj?: LogObj): void;
+    error(message: string, obj?: LogObj): void;
+    sub(name: string, obj?: LogObj): Logger;
+}
+
+/**
+ * A high-level API for managing the peer-to-peer WebRTC connection. Provides
+ *  access to lower-level {@link RTCPeerConnection} functionality. Including
+ *  access to underlying media tracks, data channels, and connection state.
+ *
+ * Usage:
+ * @example `peer.onsession = (session) => {console.log(session.otherPeerId())};`
+ */
+interface ISession {
+    /**
+     * Adds a media track to the connection. Typically used for sending audio or video.
+     * See {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/addTrack}
+     * @returns {RTCRtpSender}
+     */
+    addTrack(...args: Parameters<RTCPeerConnection["addTrack"]>): RTCRtpSender;
+    /**
+     * Removes a media track from the connection. Useful for stopping
+     * transmission of a specific track.
+     * See {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/removeTrack}
+     * @returns {void}
+     */
+    removeTrack(...args: Parameters<RTCPeerConnection["removeTrack"]>): void;
+    /**
+     * Creates a {@link RTCDataChannel} on the connection for arbitrary data transfer.
+     * See {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/createDataChannel}
+     */
+    createDataChannel(...args: Parameters<RTCPeerConnection["createDataChannel"]>): RTCDataChannel;
+    /**
+     * Retrieves the current connection state of the underlying RTCPeerConnection
+     * See {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/connectionState}
+     * @returns {RTCPeerConnectionState}
+     */
+    get connectionState(): RTCPeerConnectionState;
+    /**
+     * Callback triggered when a {@link RTCDataChannel} is created or received.
+     * See {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/ondatachannel}
+     * @example ```peer.onsession = (session) => {
+     *  session.ondatachannel = (event) => {
+     *      const channel = event.channel;
+     *      channel.onmessage = (e) => console.log("Received message:", e.data);
+     *  };```
+     */
+    ondatachannel: RTCPeerConnection["ondatachannel"];
+    /**
+     * Callback triggered when the connection state changes.
+     * See {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/onconnectionstatechange}
+     */
+    onconnectionstatechange: RTCPeerConnection["onconnectionstatechange"];
+    /**
+     * Callback invoked when a new media track is added to the connection.
+     * See {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/ontrack}
+     */
+    ontrack: RTCPeerConnection["ontrack"];
+    /**
+     * Closes the session, aborting all pending tasks, and cleaning up resources.
+     * Publishes events and logs about the closure.
+     * @param {string} [reason] - (optional) A reason for closing the session.
+     * @returns {void}
+     * @example `mysession.close("Session ended by user");`
+     */
+    close(reason?: string): void;
+    /**
+     * Retrieves the identifier of the other peer in the connection.
+     * @returns {string} The peer ID of the connected peer. Valid UTF-8 string of 1-16 characters.
+     * @example ```console.log(`Connected to peer: ${session.otherPeerId()}`);```
+     */
+    get otherPeerId(): string;
+    /**
+     * Retrieves the connection identifier for the current connection.
+     * Connection IDs are typically unique and help identify connections.
+     * @returns {number} The connection ID for the peer connection.
+     * @example
+     * ```console.log(`Connection ID: ${mySession.otherConnId()}`);```
+     */
+    get otherConnId(): number;
+}
+/**
+ * Options used to configure a Peer.
+ * @interface PeerOptionsFull
+ * @example```
+ * const options: PeerOptionsFull = {
+ *   groupId: "group-123", // Valid UTF-8 strings of 1-16 characters.
+ *   peerId: "peer-456",   // Valid UTF-8 strings of 1-16 characters.
+ *   token: "eyJhbGc...49nLmBCg"
+ * };```
+ */
+interface PeerOptionsFull {
+    /**
+     * Identifier for the group which the peer belongs to. Must be a valid UTF-8
+     * string of 1-16 characters.
+     * @type {string} groupId
+     */
+    groupId: string;
+    /**
+     * Identifier for the peer. Must be a valid UTF-8 string of 1-16 characters.
+     * @type {string} peerId
+     */
+    peerId: string;
+    /**
+     * PulseBeam authentication token for the peer. JWT token generated by `jsr:@pulsebeam/server`
+     * @type {string} token
+     */
+    token: string;
+    /**
+     * (Optional) Base URL for API calls. Defaults to using our servers: "https://cloud.pulsebeam.dev/twirp".
+     * @type {string | undefined} [baseUrl]
+     */
+    baseUrl?: string;
+    /**
+     * (Optional) If true, enforces relay-only connections, such as those passed through a TURN server. Defaults to allowing all connection types (such as direct peer to peer). For more details see {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/RTCPeerConnection#icetransportpolicy}
+     * @type {boolean | undefined} [forceRelay]
+     */
+    forceRelay?: boolean;
+    /**
+     * (Optional) Add Ice Servers. Defaults to using our servers. For more details see {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/RTCPeerConnection#iceservers}
+     * @type {RTCIceServer[] | undefined} [iceServers]
+     */
+    iceServers?: RTCIceServer[];
+}
+type PeerOptions = Omit<PeerOptionsFull, "groupId" | "peerId">;
+/**
+ * Represents the possible states for a Peer.
+ *
+ * @readonly
+ * @enum {string}
+ * Possible values:
+ *   - `"new"`: The peer has been created.
+ *   - `"closed"`: The peer has been closed.
+ */
+type PeerState = "new" | "closed";
+/**
+ * Peer is a mediator for signaling, connecting, and managing sessions.
+ */
+declare class Peer {
+    private transport;
+    private readonly logger;
+    private sessions;
+    private _state;
+    /**
+     * Callback invoked when a new session is established.
+     * @param _s Session object
+     */
+    onsession: (_s: ISession) => void;
+    /**
+     * Callback invoked when the peer’s state changes.
+     */
+    onstatechange: () => void;
+    /**
+     * Identifier for the peer. Valid UTF-8 string of 1-16 characters.
+     */
+    readonly peerId: string;
+    /**
+     * Construct a Peer. Helper available: see {@link createPeer} function
+     * @param logger Logger instance for logging events.
+     * @param client Tunnel client for signaling.
+     * @param opts Configuration options for the peer.
+     * @param isRecoverable Function to determine if an error is recoverable.
+     */
+    constructor(logger: Logger, client: ITunnelClient, opts: PeerOptionsFull, isRecoverable: (_err: unknown) => boolean);
+    /**
+     * Starts the peer, making it ready to establish connections.
+     * Peers must be started before a connection can occur.
+     *
+     * @returns {void}
+     * @throws {Error} When the peer was previously closed.
+     */
+    start(): void;
+    /**
+     * Closes the peer. Releases associated resources.
+     * Signals to the AbortController passed to connect if connect was called.
+     *
+     * @async
+     * @returns {Promise<void>} Resolves when the peer has been closed.
+     */
+    close(): Promise<void>;
+    /**
+     * Establishes a connection with another peer in the specified group.
+     * Peer should be started before calling connect.
+     *
+     * Check the log output for troubleshooting information.
+     *
+     * @async
+     * @param {string} otherGroupId The ID of the group the other peer belongs to.
+     * Valid UTF-8 string of 1-16 characters.
+     * @param {string} otherPeerId The ID of the peer you want to connect to.
+     * Valid UTF-8 string of 1-16 characters.
+     * @param {AbortSignal} signal Handle cancellations or cancel the connection attempt.
+     * @returns {Promise<void>} Resolves when the connection has been established,
+     *                          an unrecoverable error (e.g., network connection issues, internal errors) occurs,
+     *                          or the maximum retry attempts are reached.
+     */
+    connect(otherGroupId: string, otherPeerId: string, signal: AbortSignal): Promise<void>;
+    /**
+     * Gets the current state of the peer. For state info see {@link PeerState}
+     * @returns {PeerState} The current state of the peer
+     */
+    get state(): PeerState;
+    /** internal @private */
+    private setState;
+}
+/**
+ * Helper to create a new Peer instance
+ * @param opts Configuration options for the peer.
+ * @returns {Promise<Peer>} Resolves to the newly created Peer
+ * @throws {Error} When unable to connect to signaling server. Likely networking issue.
+ */
+declare function createPeer(opts: PeerOptions): Promise<Peer>;
+
+export { type ISession, Peer, type PeerOptions, type PeerOptionsFull, type PeerState, createPeer };