@convbased/sdk 0.1.0

package/src/endpoints.ts

@@ -0,0 +1,8 @@
+// Production endpoints baked into the SDK. These mirror Convbased-Web's
+// `.env` (VITE_WS_ENDPOINT / VITE_API_BASE_URL) and are considered stable —
+// they're consumed by every Convbased client today. Override only for
+// self-hosted deployments or local development.
+export const DEFAULT_SIGNALING_URL =
+	"wss://api.weights.chat/api/signaling/ws";
+export const DEFAULT_GRAPHQL_URL =
+	"https://api.weights.chat/api/v1/graphql";

package/src/events.ts

@@ -0,0 +1,38 @@
+// Minimal typed event emitter; we avoid pulling Node's EventEmitter so the
+// SDK stays browser-first with no polyfill chain.
+
+export type Listener<T> = (payload: T) => void;
+
+export class TypedEmitter<TEvents extends Record<string, unknown>> {
+	private readonly listeners: {
+		[K in keyof TEvents]?: Set<Listener<TEvents[K]>>;
+	} = {};
+
+	on<K extends keyof TEvents>(event: K, fn: Listener<TEvents[K]>): () => void {
+		(this.listeners[event] ??= new Set()).add(fn);
+		return () => this.off(event, fn);
+	}
+
+	off<K extends keyof TEvents>(event: K, fn: Listener<TEvents[K]>): void {
+		this.listeners[event]?.delete(fn);
+	}
+
+	emit<K extends keyof TEvents>(event: K, payload: TEvents[K]): void {
+		const set = this.listeners[event];
+		if (!set) return;
+		for (const fn of set) {
+			try {
+				fn(payload);
+			} catch (e) {
+				// Listeners shouldn't crash the emitter.
+				console.error(`[convbased-sdk] listener for "${String(event)}" threw:`, e);
+			}
+		}
+	}
+
+	removeAllListeners(): void {
+		for (const key of Object.keys(this.listeners)) {
+			delete this.listeners[key as keyof TEvents];
+		}
+	}
+}

package/src/graphql.ts

@@ -0,0 +1,58 @@
+// Shared GraphQL transport for the Convbased service. Authentication mirrors
+// the server middleware: `x-api-key: <key>` for API keys, or
+// `Authorization: Bearer <jwt>` for access tokens.
+
+export interface GraphQLAuth {
+	apiKey?: string;
+	accessToken?: string;
+}
+
+export interface GraphQLRequestArgs<V> extends GraphQLAuth {
+	graphqlUrl: string;
+	query: string;
+	variables?: V;
+	signal?: AbortSignal;
+}
+
+/**
+ * Issue a single GraphQL operation and return `data`. Throws on HTTP failure
+ * or when the response carries a non-empty `errors` array — the thrown
+ * `Error.message` is the first server-reported message (often an i18n key the
+ * caller can localize).
+ */
+export async function graphqlRequest<T, V = Record<string, unknown>>(
+	args: GraphQLRequestArgs<V>
+): Promise<T> {
+	const headers: Record<string, string> = {
+		"content-type": "application/json",
+	};
+	if (args.apiKey) headers["x-api-key"] = args.apiKey;
+	else if (args.accessToken) {
+		headers["authorization"] = `Bearer ${args.accessToken}`;
+	}
+
+	const res = await fetch(args.graphqlUrl, {
+		method: "POST",
+		headers,
+		body: JSON.stringify({ query: args.query, variables: args.variables }),
+		signal: args.signal,
+	});
+
+	if (!res.ok) {
+		throw new Error(
+			`GraphQL request failed: HTTP ${res.status} ${res.statusText}`
+		);
+	}
+
+	const json = (await res.json()) as {
+		data?: T;
+		errors?: Array<{ message: string }>;
+	};
+	if (json.errors?.length) {
+		throw new Error(json.errors.map((e) => e.message).join("; "));
+	}
+	if (json.data === undefined || json.data === null) {
+		throw new Error("GraphQL response contained no data");
+	}
+	return json.data;
+}

package/src/index.ts

@@ -0,0 +1,50 @@
+export {
+	ConvbasedClient,
+	type TaskAckEvent,
+	type TaskProgressEvent,
+	type TaskFinishedEvent,
+	type StartTaskOptions,
+	type RunFileInferenceOptions,
+} from "./client.js";
+export {
+	TtsClient,
+	type TtsClientOptions,
+	type TtsParams,
+	type TtsJob,
+	type TtsJobStatus,
+	type TtsResult,
+	type TtsPricing,
+	type SubmitTtsOptions,
+	type SynthesizeOptions,
+} from "./tts.js";
+export {
+	uploadAudio,
+	requestAudioUpload,
+	putToPresigned,
+	type PresignedUpload,
+	type HeaderKV,
+} from "./upload.js";
+export { graphqlRequest, type GraphQLAuth } from "./graphql.js";
+export { applyOpusSdpOptions } from "./sdp.js";
+export {
+	fetchRTCServers,
+	DEFAULT_STUN_SERVERS,
+} from "./rtcServers.js";
+export {
+	DEFAULT_SIGNALING_URL,
+	DEFAULT_GRAPHQL_URL,
+} from "./endpoints.js";
+export {
+	RTCStatusCode,
+	type ConnectOptions,
+	type ConnectionState,
+	type ConnectionStats,
+	type ConvbasedClientOptions,
+	type FileInferencePreferences,
+	type IncomingMessage,
+	type OutgoingMessage,
+	type RTCPreferences,
+	type RTCServersConfig,
+	type ServerMessageEvent,
+	type TaskStatus,
+} from "./types.js";

package/src/rtcServers.ts

@@ -0,0 +1,38 @@
+import { graphqlRequest, type GraphQLAuth } from "./graphql.js";
+import type { RTCServersConfig } from "./types.js";
+
+/**
+ * Fetch TURN credentials from the Convbased GraphQL service. The query matches
+ * the one used by Convbased-Web's `getRTCServers`. Authentication uses the
+ * same API key / access token passed to the SDK.
+ */
+export async function fetchRTCServers(
+	args: GraphQLAuth & {
+		graphqlUrl: string;
+		signal?: AbortSignal;
+	}
+): Promise<RTCServersConfig> {
+	const data = await graphqlRequest<{ rtcServers?: RTCServersConfig }>({
+		graphqlUrl: args.graphqlUrl,
+		apiKey: args.apiKey,
+		accessToken: args.accessToken,
+		signal: args.signal,
+		query: /* GraphQL */ `
+			query {
+				rtcServers {
+					urls
+					username
+					credential
+				}
+			}
+		`,
+	});
+	if (!data.rtcServers) {
+		throw new Error("rtcServers returned an empty payload");
+	}
+	return data.rtcServers;
+}
+
+export const DEFAULT_STUN_SERVERS: RTCServersConfig[] = [
+	{ urls: ["stun:stun.l.google.com:19302"] },
+];

package/src/sdp.ts

@@ -0,0 +1,45 @@
+// SDP mangling helpers. Mirrors `setAudioParameters` in Convbased-Web — we
+// rewrite the Opus `a=fmtp:` line so the offer requests our target bitrate,
+// stereo mode, and inband FEC. The signaling node passes the SDP through to
+// aiortc largely unchanged, so changes here directly shape the negotiated
+// audio.
+
+export interface OpusSdpOptions {
+	bitrateKbps: number;
+	stereo: boolean;
+}
+
+export function applyOpusSdpOptions(sdp: string, opts: OpusSdpOptions): string {
+	const lines = sdp.split("\r\n");
+	let payloadType: string | null = null;
+
+	for (const line of lines) {
+		const match = line.match(/a=rtpmap:(\d+) opus\/48000\/2/);
+		if (match) {
+			payloadType = match[1]!;
+			break;
+		}
+	}
+
+	if (!payloadType) return sdp;
+
+	let fmtpIndex = lines.findIndex((line) =>
+		line.startsWith(`a=fmtp:${payloadType}`)
+	);
+
+	if (fmtpIndex === -1) {
+		lines.push(`a=fmtp:${payloadType}`);
+		fmtpIndex = lines.length - 1;
+	}
+
+	let fmtp = lines[fmtpIndex]!;
+	fmtp = fmtp.replace(/;\s*stereo=\d/, "");
+	fmtp = fmtp.replace(/;\s*maxaveragebitrate=\d+/, "");
+
+	if (opts.stereo) fmtp += "; stereo=1";
+	fmtp += `; maxaveragebitrate=${opts.bitrateKbps * 1000}`;
+	if (!fmtp.includes("useinbandfec=1")) fmtp += "; useinbandfec=1";
+
+	lines[fmtpIndex] = fmtp;
+	return lines.join("\r\n");
+}

package/src/signaling.ts

@@ -0,0 +1,172 @@
+import type { IncomingMessage, OutgoingMessage } from "./types.js";
+
+export interface SignalingChannelOptions {
+	signalingUrl: string;
+	apiKey?: string;
+	accessToken?: string;
+	connectTimeoutMs: number;
+	logger: Pick<Console, "debug" | "info" | "warn" | "error">;
+}
+
+export interface SignalingHandlers {
+	onMessage: (msg: IncomingMessage) => void;
+	onClose: (event: CloseEvent) => void;
+	onError: (event: Event) => void;
+}
+
+/**
+ * Thin WebSocket wrapper for the Convbased signaling endpoint. Builds the URL
+ * (`${base}/signaling/ws?api_key=…`), waits for `open`, and exposes JSON
+ * send/recv plus a 10s keepalive ping to match the server's expectations.
+ */
+export class SignalingChannel {
+	private ws: WebSocket | null = null;
+	private pingTimer: ReturnType<typeof setInterval> | null = null;
+	private handlers: SignalingHandlers | null = null;
+
+	constructor(private readonly opts: SignalingChannelOptions) {}
+
+	get isOpen(): boolean {
+		return this.ws?.readyState === WebSocket.OPEN;
+	}
+
+	async connect(handlers: SignalingHandlers): Promise<void> {
+		if (this.ws) {
+			throw new Error("SignalingChannel is already connected");
+		}
+		this.handlers = handlers;
+
+		const url = this.buildUrl();
+		this.opts.logger.debug?.("[convbased-sdk] connecting signaling:", url);
+		const ws = new WebSocket(url);
+		this.ws = ws;
+
+		await new Promise<void>((resolve, reject) => {
+			const timeout = setTimeout(() => {
+				cleanup();
+				try {
+					ws.close();
+				} catch {
+					/* ignore */
+				}
+				reject(new Error("Signaling WebSocket connect timeout"));
+			}, this.opts.connectTimeoutMs);
+
+			const onOpen = () => {
+				cleanup();
+				resolve();
+			};
+			const onError = (e: Event) => {
+				cleanup();
+				reject(
+					new Error(
+						`Signaling WebSocket failed to open: ${describeEvent(e)}`
+					)
+				);
+			};
+			const onClose = (e: CloseEvent) => {
+				cleanup();
+				reject(
+					new Error(
+						`Signaling WebSocket closed before open (code=${e.code}, reason=${e.reason || "?"})`
+					)
+				);
+			};
+			const cleanup = () => {
+				clearTimeout(timeout);
+				ws.removeEventListener("open", onOpen);
+				ws.removeEventListener("error", onError);
+				ws.removeEventListener("close", onClose);
+			};
+			ws.addEventListener("open", onOpen);
+			ws.addEventListener("error", onError);
+			ws.addEventListener("close", onClose);
+		});
+
+		ws.addEventListener("message", (e) => this.handleMessage(e));
+		ws.addEventListener("close", (e) => this.handleClose(e));
+		ws.addEventListener("error", (e) => this.handlers?.onError(e));
+
+		// The signaling server pings every 10s and expects us to keep the
+		// socket warm. We mirror that cadence rather than relying on TCP
+		// keepalive, which most browsers don't expose.
+		this.pingTimer = setInterval(() => {
+			if (this.isOpen) this.send({ type: "ping" });
+		}, 10_000);
+	}
+
+	send(msg: OutgoingMessage): void {
+		if (!this.isOpen) {
+			throw new Error("Signaling WebSocket is not open");
+		}
+		this.ws!.send(JSON.stringify(msg));
+	}
+
+	close(code = 1000, reason = "client close"): void {
+		if (this.pingTimer) {
+			clearInterval(this.pingTimer);
+			this.pingTimer = null;
+		}
+		if (this.ws && this.ws.readyState <= WebSocket.OPEN) {
+			try {
+				this.ws.close(code, reason);
+			} catch {
+				/* ignore */
+			}
+		}
+		this.ws = null;
+	}
+
+	private handleMessage(event: MessageEvent): void {
+		if (typeof event.data !== "string") return;
+		let parsed: IncomingMessage;
+		try {
+			parsed = JSON.parse(event.data) as IncomingMessage;
+		} catch (e) {
+			this.opts.logger.warn?.(
+				"[convbased-sdk] dropping non-JSON signaling frame:",
+				event.data
+			);
+			return;
+		}
+		this.handlers?.onMessage(parsed);
+	}
+
+	private handleClose(event: CloseEvent): void {
+		if (this.pingTimer) {
+			clearInterval(this.pingTimer);
+			this.pingTimer = null;
+		}
+		this.handlers?.onClose(event);
+	}
+
+	private buildUrl(): string {
+		// `signalingUrl` may be:
+		//   - the full final URL ending in `/ws` (production default — used as-is)
+		//   - a bare host (e.g. `ws://localhost:3010`) — we append `/signaling/ws`
+		//   - something already containing `/signaling` — we append `/ws`
+		let base = this.opts.signalingUrl.trim();
+		if (base.endsWith("/")) base = base.slice(0, -1);
+
+		let finalUrl: string;
+		if (/\/ws$/i.test(base)) {
+			finalUrl = base;
+		} else if (/\/signaling$/i.test(base)) {
+			finalUrl = `${base}/ws`;
+		} else {
+			finalUrl = `${base}/signaling/ws`;
+		}
+
+		const url = new URL(finalUrl);
+		if (this.opts.apiKey) url.searchParams.set("api_key", this.opts.apiKey);
+		if (this.opts.accessToken && !this.opts.apiKey) {
+			url.searchParams.set("token", this.opts.accessToken);
+		}
+		return url.toString();
+	}
+}
+
+function describeEvent(e: Event): string {
+	if (e instanceof ErrorEvent && e.message) return e.message;
+	return e.type || "unknown error";
+}