@abraca/dabra 1.0.2 → 1.0.3

package/src/webrtc/types.ts

@@ -0,0 +1,159 @@
+// ── Signaling Wire Protocol ─────────────────────────────────────────────────
+// Mirrors the Rust server's Incoming/Outgoing enums in signaling.rs exactly.
+// All messages are JSON text frames with a "type" discriminator.
+
+export type SignalingIncoming =
+	| { type: "join" }
+	| { type: "leave" }
+	| { type: "offer"; to: string; sdp: string }
+	| { type: "answer"; to: string; sdp: string }
+	| { type: "ice"; to: string; candidate: string }
+	| { type: "mute"; muted: boolean }
+	| { type: "media-state"; video: boolean; screen: boolean }
+	| { type: "profile"; name: string; color: string }
+	| { type: "pong" };
+
+export type SignalingOutgoing =
+	| { type: "welcome"; peer_id: string; peers: PeerInfo[] }
+	| {
+			type: "joined";
+			peer_id: string;
+			user_id: string;
+			muted: boolean;
+			video: boolean;
+			screen: boolean;
+			name: string | null;
+			color: string | null;
+	  }
+	| { type: "left"; peer_id: string }
+	| { type: "offer"; from: string; sdp: string }
+	| { type: "answer"; from: string; sdp: string }
+	| { type: "ice"; from: string; candidate: string }
+	| { type: "mute"; peer_id: string; muted: boolean }
+	| {
+			type: "media-state";
+			peer_id: string;
+			video: boolean;
+			screen: boolean;
+	  }
+	| { type: "profile"; peer_id: string; name: string; color: string }
+	| { type: "ping" }
+	| { type: "error"; code: string; message: string };
+
+// ── Peer State ──────────────────────────────────────────────────────────────
+
+export interface PeerInfo {
+	peer_id: string;
+	user_id: string;
+	muted: boolean;
+	video: boolean;
+	screen: boolean;
+	name: string | null;
+	color: string | null;
+}
+
+export interface PeerState extends PeerInfo {
+	connectionState: RTCPeerConnectionState | "new";
+}
+
+// ── File Transfer ───────────────────────────────────────────────────────────
+
+export interface FileTransferMeta {
+	transferId: string;
+	filename: string;
+	mimeType: string;
+	totalSize: number;
+	chunkSize: number;
+	totalChunks: number;
+}
+
+export type FileTransferStatus =
+	| "pending"
+	| "sending"
+	| "receiving"
+	| "complete"
+	| "cancelled"
+	| "error";
+
+/** Data channel file transfer message type discriminators (first byte). */
+export const FILE_MSG = {
+	START: 0x01,
+	CHUNK: 0x02,
+	COMPLETE: 0x03,
+	CANCEL: 0x04,
+} as const;
+
+/** Data channel Y.js message type discriminators (first byte). */
+export const YJS_MSG = {
+	SYNC: 0x00,
+	UPDATE: 0x01,
+} as const;
+
+// ── Data Channel Names ──────────────────────────────────────────────────────
+
+export const CHANNEL_NAMES = {
+	YJS_SYNC: "yjs-sync",
+	AWARENESS: "awareness",
+	FILE_TRANSFER: "file-transfer",
+	CUSTOM: "custom",
+} as const;
+
+// ── Configuration ───────────────────────────────────────────────────────────
+
+export interface AbracadabraWebRTCConfiguration {
+	/** Document ID for the signaling room. */
+	docId: string;
+
+	/** Server base URL (http/https). Signaling URL derived automatically. */
+	url: string;
+
+	/** JWT token or async token factory. */
+	token: string | (() => string) | (() => Promise<string>);
+
+	/** Optional Y.Doc to sync over data channels (hybrid mode). */
+	document?: InstanceType<typeof import("yjs").Doc> | null;
+
+	/** Optional Awareness instance for presence sync over data channels. */
+	awareness?: InstanceType<
+		typeof import("y-protocols/awareness").Awareness
+	> | null;
+
+	/** ICE server configuration. Defaults to Google STUN. */
+	iceServers?: RTCIceServer[];
+
+	/** Display name for this peer. */
+	displayName?: string;
+
+	/** Color identifier for this peer. */
+	color?: string;
+
+	/** Enable Y.js document sync over data channels. Default: true when document is provided. */
+	enableDocSync?: boolean;
+
+	/** Enable awareness sync over data channels. Default: true when awareness is provided. */
+	enableAwarenessSync?: boolean;
+
+	/** Enable file transfer channel. Default: false. */
+	enableFileTransfer?: boolean;
+
+	/** Max file chunk size in bytes. Default: 16384 (16KB). */
+	fileChunkSize?: number;
+
+	/** Auto-connect on construction. Default: true. */
+	autoConnect?: boolean;
+
+	/** WebSocket polyfill for signaling (e.g. for Node.js). */
+	WebSocketPolyfill?: any;
+}
+
+export const DEFAULT_ICE_SERVERS: RTCIceServer[] = [
+	{ urls: "stun:stun.l.google.com:19302" },
+];
+
+export const DEFAULT_FILE_CHUNK_SIZE = 16384; // 16KB
+
+/** UUID v4 transfer ID length when encoded as raw bytes. */
+export const TRANSFER_ID_BYTES = 16;
+
+/** SHA-256 hash length in bytes. */
+export const SHA256_BYTES = 32;