@abraca/dabra 1.0.2 → 1.0.4

package/dist/index.d.ts

@@ -415,6 +415,12 @@ declare class AbracadabraClient {
    * No auth required.
    */
   serverInfo(): Promise<ServerInfo>;
+  /**
+   * Fetch ICE server configuration for WebRTC peer connections.
+   * Falls back to default Google STUN server if the endpoint is unavailable.
+   * No auth required.
+   */
+  getIceServers(): Promise<RTCIceServer[]>;
   private request;
   private toError;
   private loadPersistedToken;
@@ -935,6 +941,8 @@ interface UserProfile {
   email: string | null;
   displayName: string | null;
   role: string;
+  /** Account-level Ed25519 public key (base64url). Canonical user identity. */
+  publicKey: string | null;
 }
 interface DocumentMeta {
   id: string;
@@ -1591,4 +1599,358 @@ declare class BackgroundSyncManager extends EventEmitter {
   private _walkXml;
 }
 //#endregion
-export { AbracadabraBaseProvider, AbracadabraBaseProviderConfiguration, AbracadabraClient, AbracadabraClientConfig, AbracadabraOutgoingMessageArguments, AbracadabraProvider, AbracadabraProviderConfiguration, AbracadabraWS, AbracadabraWSConfiguration, AbracadabraWebSocketConn, AuthMessageType, AuthorizedScope, AwarenessError, BackgroundSyncManager, type BackgroundSyncManagerOptions, BackgroundSyncPersistence, CloseEvent, CompleteAbracadabraBaseProviderConfiguration, CompleteAbracadabraWSConfiguration, CompleteHocuspocusProviderConfiguration, CompleteHocuspocusProviderWebsocketConfiguration, ConnectionTimeout, Constructable, ConstructableOutgoingMessage, CryptoIdentity, CryptoIdentityKeystore, type DocEncryptionInfo, DocKeyManager, type DocSyncState, DocumentCache, type DocumentCacheOptions, DocumentMeta, E2EAbracadabraProvider, E2EOfflineStore, EffectiveRole, EncryptedYMap, EncryptedYText, FileBlobStore, Forbidden, HealthStatus, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, InviteRow, MessageTooBig, MessageType, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, PendingSubdoc, PermissionEntry, PublicKeyInfo, ResetConnection, SearchIndex, SearchResult, ServerInfo, SpaceMeta, StatesArray, SubdocMessage, SubdocRegisteredEvent, Unauthorized, UploadInfo, UploadMeta, UploadQueueEntry, UploadQueueStatus, UserProfile, WebSocketStatus, WsReadyStates, attachUpdatedAtObserver, awarenessStatesToArray, decryptField, encryptField, makeEncryptedYMap, makeEncryptedYText, onAuthenticatedParameters, onAuthenticationFailedParameters, onAwarenessChangeParameters, onAwarenessUpdateParameters, onCloseParameters, onDisconnectParameters, onMessageParameters, onOpenParameters, onOutgoingMessageParameters, onStatelessParameters, onStatusParameters, onSubdocLoadedParameters, onSubdocRegisteredParameters, onSyncedParameters, onUnsyncedChangesParameters, readAuthMessage, writeAuthenticated, writeAuthentication, writePermissionDenied, writeTokenSyncRequest };
+//#region packages/provider/src/webrtc/DataChannelRouter.d.ts
+declare class DataChannelRouter extends EventEmitter {
+  private connection;
+  private channels;
+  constructor(connection: RTCPeerConnection);
+  /** Create a named data channel (initiator side). */
+  createChannel(name: string, options?: RTCDataChannelInit): RTCDataChannel;
+  /** Create the standard set of channels for Abracadabra WebRTC. */
+  createDefaultChannels(opts: {
+    enableDocSync: boolean;
+    enableAwareness: boolean;
+    enableFileTransfer: boolean;
+  }): void;
+  getChannel(name: string): RTCDataChannel | null;
+  isOpen(name: string): boolean;
+  private registerChannel;
+  close(): void;
+  destroy(): void;
+}
+//#endregion
+//#region packages/provider/src/webrtc/types.d.ts
+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";
+};
+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;
+};
+interface PeerInfo {
+  peer_id: string;
+  user_id: string;
+  muted: boolean;
+  video: boolean;
+  screen: boolean;
+  name: string | null;
+  color: string | null;
+}
+interface PeerState extends PeerInfo {
+  connectionState: RTCPeerConnectionState | "new";
+}
+interface FileTransferMeta {
+  transferId: string;
+  filename: string;
+  mimeType: string;
+  totalSize: number;
+  chunkSize: number;
+  totalChunks: number;
+}
+type FileTransferStatus = "pending" | "sending" | "receiving" | "complete" | "cancelled" | "error";
+declare const CHANNEL_NAMES: {
+  readonly YJS_SYNC: "yjs-sync";
+  readonly AWARENESS: "awareness";
+  readonly FILE_TRANSFER: "file-transfer";
+  readonly CUSTOM: "custom";
+};
+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 Y.Doc> | null;
+  /** Optional Awareness instance for presence sync over data channels. */
+  awareness?: InstanceType<typeof 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;
+}
+declare const DEFAULT_ICE_SERVERS: RTCIceServer[];
+declare const DEFAULT_FILE_CHUNK_SIZE = 16384;
+//#endregion
+//#region packages/provider/src/webrtc/FileTransferChannel.d.ts
+/**
+ * Handle for tracking a file transfer in progress.
+ */
+declare class FileTransferHandle extends EventEmitter {
+  readonly transferId: string;
+  progress: number;
+  status: FileTransferStatus;
+  private abortController;
+  constructor(transferId: string);
+  cancel(): void;
+  get signal(): AbortSignal;
+  /** @internal */
+  _setProgress(p: number): void;
+  /** @internal */
+  _setStatus(s: FileTransferStatus): void;
+}
+/**
+ * Chunked binary file transfer over a dedicated WebRTC data channel.
+ */
+declare class FileTransferChannel extends EventEmitter {
+  private readonly router;
+  private receives;
+  private chunkSize;
+  private channelMessageHandler;
+  constructor(router: DataChannelRouter, chunkSize?: number);
+  /** Send a file to a peer. Returns a handle for tracking progress. */
+  send(file: File | Blob, filename: string): Promise<FileTransferHandle>;
+  private handleMessage;
+  private handleStart;
+  private handleChunk;
+  private handleComplete;
+  private handleCancel;
+  destroy(): void;
+}
+//#endregion
+//#region packages/provider/src/webrtc/AbracadabraWebRTC.d.ts
+/**
+ * Optional WebRTC provider for peer-to-peer Y.js sync, awareness, and file transfer.
+ *
+ * Uses the server's signaling endpoint (`/ws/:doc_id/signaling`) for connection
+ * negotiation, then establishes direct data channels between peers. Designed to
+ * work alongside `AbracadabraProvider` — the server remains the persistence layer,
+ * while WebRTC provides low-latency P2P sync.
+ *
+ * Falls back to a no-op when `RTCPeerConnection` is unavailable (e.g. Node.js).
+ */
+declare class AbracadabraWebRTC extends EventEmitter {
+  private signaling;
+  private peerConnections;
+  private yjsChannels;
+  private fileChannels;
+  private readonly config;
+  readonly peers: Map<string, PeerState>;
+  localPeerId: string | null;
+  isConnected: boolean;
+  constructor(configuration: AbracadabraWebRTCConfiguration);
+  /**
+   * Create an AbracadabraWebRTC instance from an existing provider,
+   * reusing its document, awareness, URL, and token.
+   */
+  static fromProvider(provider: AbracadabraProvider, options?: Partial<AbracadabraWebRTCConfiguration>): AbracadabraWebRTC;
+  connect(): Promise<void>;
+  disconnect(): void;
+  destroy(): void;
+  setMuted(muted: boolean): void;
+  setMediaState(video: boolean, screen: boolean): void;
+  setProfile(name: string, color: string): void;
+  /**
+   * Send a file to a specific peer. Returns a handle for tracking progress.
+   */
+  sendFile(peerId: string, file: File | Blob, filename: string): Promise<FileTransferHandle | null>;
+  /**
+   * Send a file to all connected peers. Returns an array of handles.
+   */
+  broadcastFile(file: File | Blob, filename: string): Promise<FileTransferHandle[]>;
+  /**
+   * Send a custom string message to a specific peer via a data channel.
+   */
+  sendCustomMessage(peerId: string, payload: string): void;
+  /**
+   * Send a custom string message to all connected peers.
+   */
+  broadcastCustomMessage(payload: string): void;
+  private addPeer;
+  private removePeer;
+  private removeAllPeers;
+  private createPeerConnection;
+  private attachDataHandlers;
+  private initiateConnection;
+  private handleOffer;
+  private buildSignalingUrl;
+}
+//#endregion
+//#region packages/provider/src/webrtc/SignalingSocket.d.ts
+interface SignalingSocketConfiguration {
+  /** WebSocket URL for the signaling endpoint. */
+  url: string;
+  /** JWT token or async token factory for auth. */
+  token: string | (() => string) | (() => Promise<string>);
+  /** Auto-connect on construction. Default: true. */
+  autoConnect?: boolean;
+  /** WebSocket polyfill (e.g. for Node.js). */
+  WebSocketPolyfill?: any;
+  /** Retry delay in ms. Default: 1000. */
+  delay?: number;
+  /** Retry factor. Default: 2. */
+  factor?: number;
+  /** Min retry delay. Default: 1000. */
+  minDelay?: number;
+  /** Max retry delay. Default: 30000. */
+  maxDelay?: number;
+  /** Randomize delay. Default: true. */
+  jitter?: boolean;
+  /** Max retry attempts (0 = unlimited). Default: 0. */
+  maxAttempts?: number;
+}
+declare class SignalingSocket extends EventEmitter {
+  private ws;
+  private wsHandlers;
+  private shouldConnect;
+  private cancelRetry?;
+  private connectionAttempt;
+  private readonly config;
+  localPeerId: string | null;
+  isConnected: boolean;
+  constructor(configuration: SignalingSocketConfiguration);
+  private getToken;
+  connect(): Promise<void>;
+  private createConnection;
+  private handleMessage;
+  private sendRaw;
+  sendOffer(to: string, sdp: string): void;
+  sendAnswer(to: string, sdp: string): void;
+  sendIce(to: string, candidate: string): void;
+  sendMute(muted: boolean): void;
+  sendMediaState(video: boolean, screen: boolean): void;
+  sendProfile(name: string, color: string): void;
+  sendLeave(): void;
+  disconnect(): void;
+  destroy(): void;
+  private cleanup;
+}
+//#endregion
+//#region packages/provider/src/webrtc/PeerConnection.d.ts
+declare class PeerConnection extends EventEmitter {
+  readonly connection: RTCPeerConnection;
+  readonly router: DataChannelRouter;
+  readonly peerId: string;
+  private pendingCandidates;
+  private hasRemoteDescription;
+  constructor(peerId: string, iceServers: RTCIceServer[]);
+  get connectionState(): RTCPeerConnectionState;
+  get iceConnectionState(): RTCIceConnectionState;
+  /** Create an SDP offer (initiator side). */
+  createOffer(iceRestart?: boolean): Promise<string>;
+  /** Set a remote offer and create an answer (receiver side). Returns the SDP answer. */
+  setRemoteOffer(sdp: string): Promise<string>;
+  /** Set the remote answer (initiator side). */
+  setRemoteAnswer(sdp: string): Promise<void>;
+  /** Add a remote ICE candidate. Queues if remote description not yet set. */
+  addIceCandidate(candidateJson: string): Promise<void>;
+  private flushPendingCandidates;
+  close(): void;
+  destroy(): void;
+}
+//#endregion
+//#region packages/provider/src/webrtc/YjsDataChannel.d.ts
+/**
+ * Handles Y.js document sync and awareness over WebRTC data channels.
+ *
+ * Uses the same y-protocols/sync encoding as the WebSocket provider but
+ * transported over RTCDataChannel instead. A unique origin is used to
+ * prevent echo loops with the server-based provider.
+ */
+declare class YjsDataChannel {
+  private readonly document;
+  private readonly awareness;
+  private readonly router;
+  private docUpdateHandler;
+  private awarenessUpdateHandler;
+  private channelOpenHandler;
+  private channelMessageHandler;
+  constructor(document: Y.Doc, awareness: Awareness | null, router: DataChannelRouter);
+  /** Start listening for Y.js updates and data channel messages. */
+  attach(): void;
+  /** Stop listening and clean up handlers. */
+  detach(): void;
+  destroy(): void;
+  private sendSyncStep1;
+  private handleSyncMessage;
+  private handleAwarenessMessage;
+}
+//#endregion
+export { AbracadabraBaseProvider, AbracadabraBaseProviderConfiguration, AbracadabraClient, AbracadabraClientConfig, AbracadabraOutgoingMessageArguments, AbracadabraProvider, AbracadabraProviderConfiguration, AbracadabraWS, AbracadabraWSConfiguration, AbracadabraWebRTC, type AbracadabraWebRTCConfiguration, AbracadabraWebSocketConn, AuthMessageType, AuthorizedScope, AwarenessError, BackgroundSyncManager, type BackgroundSyncManagerOptions, BackgroundSyncPersistence, CHANNEL_NAMES, CloseEvent, CompleteAbracadabraBaseProviderConfiguration, CompleteAbracadabraWSConfiguration, CompleteHocuspocusProviderConfiguration, CompleteHocuspocusProviderWebsocketConfiguration, ConnectionTimeout, Constructable, ConstructableOutgoingMessage, CryptoIdentity, CryptoIdentityKeystore, DEFAULT_FILE_CHUNK_SIZE, DEFAULT_ICE_SERVERS, DataChannelRouter, type DocEncryptionInfo, DocKeyManager, type DocSyncState, DocumentCache, type DocumentCacheOptions, DocumentMeta, E2EAbracadabraProvider, E2EOfflineStore, EffectiveRole, EncryptedYMap, EncryptedYText, FileBlobStore, FileTransferChannel, FileTransferHandle, type FileTransferMeta, type FileTransferStatus, Forbidden, HealthStatus, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, InviteRow, MessageTooBig, MessageType, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, PeerConnection, type PeerInfo, type PeerState, PendingSubdoc, PermissionEntry, PublicKeyInfo, ResetConnection, SearchIndex, SearchResult, ServerInfo, type SignalingIncoming, type SignalingOutgoing, SignalingSocket, SpaceMeta, StatesArray, SubdocMessage, SubdocRegisteredEvent, Unauthorized, UploadInfo, UploadMeta, UploadQueueEntry, UploadQueueStatus, UserProfile, WebSocketStatus, WsReadyStates, YjsDataChannel, attachUpdatedAtObserver, awarenessStatesToArray, decryptField, encryptField, makeEncryptedYMap, makeEncryptedYText, onAuthenticatedParameters, onAuthenticationFailedParameters, onAwarenessChangeParameters, onAwarenessUpdateParameters, onCloseParameters, onDisconnectParameters, onMessageParameters, onOpenParameters, onOutgoingMessageParameters, onStatelessParameters, onStatusParameters, onSubdocLoadedParameters, onSubdocRegisteredParameters, onSyncedParameters, onUnsyncedChangesParameters, readAuthMessage, writeAuthenticated, writeAuthentication, writePermissionDenied, writeTokenSyncRequest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/dabra",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",

package/src/AbracadabraClient.ts

@@ -536,6 +536,24 @@ export class AbracadabraClient {
 		return this.request<ServerInfo>("GET", "/info", { auth: false });
 	}
 
+	/**
+	 * Fetch ICE server configuration for WebRTC peer connections.
+	 * Falls back to default Google STUN server if the endpoint is unavailable.
+	 * No auth required.
+	 */
+	async getIceServers(): Promise<RTCIceServer[]> {
+		try {
+			const res = await this.request<{ iceServers: RTCIceServer[] }>(
+				"GET",
+				"/ice-servers",
+				{ auth: false },
+			);
+			return res.iceServers;
+		} catch {
+			return [{ urls: "stun:stun.l.google.com:19302" }];
+		}
+	}
+
 	// ── Internals ────────────────────────────────────────────────────────────
 
 	private async request<T = void>(

package/src/AbracadabraWS.ts

@@ -511,7 +511,9 @@ export class AbracadabraWS extends EventEmitter {
     this.emit("status", { status: WebSocketStatus.Disconnected });
 
     // Detect server-side rate-limit close (code 4429).
-    const isRateLimited = (event as any)?.code === 4429;
+    // `event` may be a CloseEvent (browser) with `.code`, or a raw number (ws/Node.js).
+    // `event` may be a CloseEvent (browser) with `.code`, or a raw number (ws/Node.js).
+    const isRateLimited = (event as any)?.code === 4429 || event === 4429;
     this.emit("disconnect", { event });
     if (isRateLimited) {
       this.emit("rateLimited");

package/src/index.ts

@@ -23,3 +23,4 @@ export { BackgroundSyncManager } from "./BackgroundSyncManager.ts";
 export type { BackgroundSyncManagerOptions } from "./BackgroundSyncManager.ts";
 export { BackgroundSyncPersistence } from "./BackgroundSyncPersistence.ts";
 export type { DocSyncState } from "./BackgroundSyncPersistence.ts";
+export * from "./webrtc/index.ts";

package/src/types.ts

@@ -166,6 +166,8 @@ export interface UserProfile {
   email: string | null;
   displayName: string | null;
   role: string;
+  /** Account-level Ed25519 public key (base64url). Canonical user identity. */
+  publicKey: string | null;
 }
 
 export interface DocumentMeta {