@decartai/sdk 0.1.22 → 0.1.23

package/dist/files/client.d.ts

@@ -27,6 +27,12 @@ type FilesClient = {
    */
   upload: (file: FileUploadInput, options?: UploadFileOptions) => Promise<FileReference>;
   get: (fileId: string) => Promise<FileReference>;
+  /**
+   * Look up an upload by the MD5 of its bytes when you no longer have the id.
+   * Resolves the newest non-expired match; rejects with `FILES_GET_ERROR` on
+   * 404, exactly like `get` does for an unknown id.
+   */
+  getByMd5: (md5: string) => Promise<FileReference>;
   delete: (fileId: string) => Promise<void>;
 };
 //#endregion

package/dist/files/client.js

@@ -4,6 +4,7 @@ import { z } from "zod";
 //#region src/files/client.ts
 const MAX_TTL_SECONDS = 720 * 60 * 60;
 const ttlSecondsSchema = z.union([z.number().int().min(60).max(MAX_TTL_SECONDS), z.literal("persistent")]);
+const MD5_HEX = /^[0-9a-f]{32}$/i;
 const createFilesClient = (opts) => {
 	const { baseUrl, apiKey, integration } = opts;
 	const upload = async (file, options) => {
@@ -28,8 +29,8 @@ const createFilesClient = (opts) => {
 		}
 		return response.json();
 	};
-	const get = async (fileId) => {
-		const response = await fetch(`${baseUrl}/v1/files/${encodeURIComponent(fileId)}`, {
+	const fetchReference = async (path) => {
+		const response = await fetch(`${baseUrl}${path}`, {
 			method: "GET",
 			headers: buildAuthHeaders({
 				apiKey,
@@ -42,6 +43,11 @@ const createFilesClient = (opts) => {
 		}
 		return response.json();
 	};
+	const get = (fileId) => fetchReference(`/v1/files/${encodeURIComponent(fileId)}`);
+	const getByMd5 = async (md5) => {
+		if (!MD5_HEX.test(md5)) throw createInvalidInputError("md5 must be 32 hex characters");
+		return fetchReference(`/v1/files/by-md5/${md5.toLowerCase()}`);
+	};
 	const deleteFile = async (fileId) => {
 		const response = await fetch(`${baseUrl}/v1/files/${encodeURIComponent(fileId)}`, {
 			method: "DELETE",
@@ -58,6 +64,7 @@ const createFilesClient = (opts) => {
 	return {
 		upload,
 		get,
+		getByMd5,
 		delete: deleteFile
 	};
 };

package/dist/files/types.d.ts

@@ -14,6 +14,12 @@ interface FileReference {
   filename: string | null;
   mime_type: string;
   size_bytes: number;
+  /**
+   * Lowercase hex MD5 of the uploaded bytes; pass it to `client.files.getByMd5(...)`
+   * to find this file again without its id. `null` on files uploaded before
+   * hashes were recorded.
+   */
+  md5: string | null;
   created_at: string;
   expires_at: string | null;
 }

package/dist/package.js

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.1.22";
+var version = "0.1.23";
 //#endregion
 export { version };

package/dist/realtime/config-realtime.js

@@ -1,4 +1,16 @@
 //#region src/realtime/config-realtime.ts
+/** Publish bitrate floor for the primary video layer (bps). */
+const MIN_VIDEO_BITRATE_BPS = 11e5;
+/** Publish bitrate cap for the primary video layer (bps). */
+const MAX_VIDEO_BITRATE_BPS = 35e5;
+/** Combined max bitrate of livekit-client's default lower simulcast layers (bps); pinned by a unit test. */
+const SIMULCAST_LOWER_LAYERS_BPS = 61e4;
+/** Fraction of the bandwidth estimate available to the video encoders. */
+const BWE_VIDEO_SHARE = .8;
+/** Bandwidth estimate (kbps) needed for the primary layer to reach `primaryBps`. */
+function estimateKbpsFor(primaryBps) {
+	return Math.round((primaryBps + SIMULCAST_LOWER_LAYERS_BPS) / BWE_VIDEO_SHARE / 1e3);
+}
 const REALTIME_CONFIG = {
 	signaling: {
 		connectTimeoutMs: 6e4,
@@ -34,8 +46,12 @@ const REALTIME_CONFIG = {
 			dynacast: false
 		},
 		defaultVideoCodec: "h264",
-		defaultMaxVideoBitrateBps: 35e5,
+		defaultMaxVideoBitrateBps: MAX_VIDEO_BITRATE_BPS,
 		vp9MaxVideoBitrateBps: 3e6,
+		/** Seeds the publisher's bandwidth estimate (a start bitrate, not a minimum). */
+		minVideoBitrateBps: MIN_VIDEO_BITRATE_BPS,
+		simulcastLowerLayersBitrateBps: SIMULCAST_LOWER_LAYERS_BPS,
+		bweVideoShare: BWE_VIDEO_SHARE,
 		defaultPublishFps: 30
 	},
 	observability: {
@@ -109,12 +125,11 @@ const REALTIME_CONFIG = {
 				fair: .01,
 				poor: .05
 			},
-			/** Upstream headroom = available BWE ÷ the intended publish bitrate (requiredUpstreamKbps). */
+			/** Available upstream bandwidth bands (kbps). Chromium-only. */
 			upstream: {
-				goodRatio: 1,
-				fairRatio: .8,
-				poorRatio: .5,
-				requiredUpstreamKbps: 3500
+				goodKbps: estimateKbpsFor(MAX_VIDEO_BITRATE_BPS),
+				fairKbps: estimateKbpsFor(MIN_VIDEO_BITRATE_BPS),
+				poorKbps: estimateKbpsFor(MIN_VIDEO_BITRATE_BPS / 2)
 			},
 			/** Rendered (inbound) frames-per-second. */
 			stall: {

package/dist/realtime/media-channel.js

@@ -3,13 +3,32 @@ import { REALTIME_CONFIG } from "./config-realtime.js";
 import { loadLiveKitClient } from "./livekit.js";
 import mitt from "mitt";
 //#region src/realtime/media-channel.ts
+const START_BITRATE_PARAM = "x-google-start-bitrate";
+/** Add `x-google-start-bitrate=<kbps>` to every video codec's fmtp line; libwebrtc reads it from the remote description. */
+function withVideoStartBitrate(sdp, kbps) {
+	const param = `${START_BITRATE_PARAM}=${kbps}`;
+	return sdp.split(/(?=^m=)/m).map((section) => {
+		if (!section.startsWith("m=video")) return section;
+		const withFmtp = new Set(Array.from(section.matchAll(/^a=fmtp:(\d+) /gm), (m) => m[1]));
+		return section.replace(/^a=fmtp:\d+ [^\r\n]*/gm, (line) => line.includes(START_BITRATE_PARAM) ? line : `${line};${param}`).replace(/^a=rtpmap:(\d+) (?!rtx|red|ulpfec|flexfec)[^\r\n]*(\r?\n)/gim, (line, pt, eol) => withFmtp.has(pt) ? line : `${line}a=fmtp:${pt} ${param}${eol}`);
+	}).join("");
+}
+function usesSimulcast(videoCodec) {
+	return (videoCodec ?? REALTIME_CONFIG.livekit.defaultVideoCodec) !== "vp9";
+}
+/** Bandwidth-estimator seed (kbps) for the publisher. */
+function getVideoStartBitrateKbps(videoCodec) {
+	const { minVideoBitrateBps, simulcastLowerLayersBitrateBps, bweVideoShare } = REALTIME_CONFIG.livekit;
+	const lowerLayers = usesSimulcast(videoCodec) ? simulcastLowerLayersBitrateBps : 0;
+	return Math.round((minVideoBitrateBps + lowerLayers) / bweVideoShare / 1e3);
+}
 function getDefaultVideoPublishOptions(source, videoCodec, frameMetadata = false) {
 	const resolvedCodec = videoCodec ?? REALTIME_CONFIG.livekit.defaultVideoCodec;
 	const maxBitrate = resolvedCodec === "vp9" ? REALTIME_CONFIG.livekit.vp9MaxVideoBitrateBps : REALTIME_CONFIG.livekit.defaultMaxVideoBitrateBps;
 	return {
 		source,
 		videoCodec: resolvedCodec,
-		simulcast: resolvedCodec !== "vp9",
+		simulcast: usesSimulcast(resolvedCodec),
 		videoEncoding: {
 			maxBitrate,
 			maxFramerate: REALTIME_CONFIG.livekit.defaultPublishFps
@@ -82,6 +101,7 @@ var LiveKitMediaChannel = class {
 		this.config.observability?.startPhase("webrtc-handshake");
 		await room.connect(opts.url, opts.token);
 		this.config.observability?.endPhase("webrtc-handshake", { success: true });
+		this.seedStartBitrate(room);
 		this.config.observability?.setLiveKitRoom(room);
 	}
 	async publishLocalTracks() {
@@ -106,6 +126,21 @@ var LiveKitMediaChannel = class {
 		this.config.observability?.setLiveKitRoom(null);
 		if (room) room.disconnect().catch(() => {});
 	}
+	/**
+	* livekit-client has no start-bitrate option for H264/VP8, so seed the estimator through the
+	* SFU answer. Installed once per room: if livekit-client itself performs a full reconnect it
+	* creates a new publisher transport, and the rest of that session ramps from the default.
+	*/
+	seedStartBitrate(room) {
+		const publisher = room.engine?.pcManager?.publisher;
+		const original = publisher?.setRemoteDescription;
+		if (!publisher || typeof original !== "function") return;
+		const kbps = getVideoStartBitrateKbps(this.config.videoCodec);
+		publisher.setRemoteDescription = (sd, offerId) => original.call(publisher, sd.type === "answer" && sd.sdp ? {
+			type: sd.type,
+			sdp: withVideoStartBitrate(sd.sdp, kbps)
+		} : sd, offerId);
+	}
 	async publishTracks(stream) {
 		if (!this.room) return;
 		for (const track of stream.getTracks()) if (track.kind === "video") {
@@ -116,4 +151,4 @@ var LiveKitMediaChannel = class {
 };
 const createLiveKitMediaChannel = (config) => new LiveKitMediaChannel(config);
 //#endregion
-export { LiveKitMediaChannel, createLiveKitMediaChannel, getDefaultVideoPublishOptions };
+export { LiveKitMediaChannel, createLiveKitMediaChannel, getDefaultVideoPublishOptions, getVideoStartBitrateKbps, withVideoStartBitrate };

package/dist/realtime/methods.js

@@ -7,7 +7,10 @@ const setInputSchema = z.object({
 	prompt: z.string().min(1).optional(),
 	enhance: z.boolean().optional().default(true),
 	/**
-	* - `Blob`/`File`/data:/http(s):/base64 string: bytes traverse the wire as base64.
+	* - `Blob`/`File`/data:/base64 string: bytes traverse the wire as base64.
+	* - `http(s):` URL: fetched, then sent as base64. Browser-oriented — the fetch
+	*   relies on the same-origin policy. Server-side, pass bytes rather than a
+	*   caller-supplied URL (fetching an arbitrary URL from a server is an SSRF risk).
 	* - `"file_..."` id (from `client.files.upload(...).id`): sent as a server-side reference.
 	*/
 	image: z.union([

package/dist/realtime/observability/connection-quality.js

@@ -47,7 +47,8 @@ function scoreMetrics(signals, thresholds, options = {}) {
 	const loss = scoreLowerBetter(signals.fractionLost, thresholds.loss.good, thresholds.loss.fair, thresholds.loss.poor);
 	let bandwidth = "good";
 	if (!options.skipBitrate) {
-		bandwidth = scoreHigherBetter(signals.availableOutgoingKbps != null ? signals.availableOutgoingKbps / thresholds.upstream.requiredUpstreamKbps : null, thresholds.upstream.goodRatio, thresholds.upstream.fairRatio, thresholds.upstream.poorRatio);
+		const { goodKbps, fairKbps, poorKbps } = thresholds.upstream;
+		bandwidth = scoreHigherBetter(signals.availableOutgoingKbps, goodKbps, fairKbps, poorKbps);
 		if (signals.qualityLimitationReason === "bandwidth") bandwidth = worst(bandwidth, "fair");
 	}
 	let stall = scoreHigherBetter(signals.fps, thresholds.stall.goodFps, thresholds.stall.fairFps, thresholds.stall.poorFps);

package/dist/utils/media.js

@@ -19,6 +19,21 @@ async function blobToBase64(blob) {
 		reader.readAsDataURL(blob);
 	});
 }
+/**
+* Normalizes an image input to a raw base64 string (no `data:` prefix).
+*
+* String inputs are interpreted by URL scheme:
+* - `data:` URL — decoded locally.
+* - `http:`/`https:` URL — fetched, then encoded. This is a browser-oriented
+*   convenience that leans on the browser's same-origin policy to bound what
+*   the fetch can read. Do NOT rely on it server-side (Node/SSR/edge) with a
+*   caller-supplied URL: fetching an arbitrary URL from a server is an SSRF
+*   vector, and this helper can't distinguish an internal host from an external
+*   one. Server-side callers should pass binary (`Blob`/`File`) instead.
+* - any other string that parses as a URL (e.g. `file:`, `blob:`, `ftp:`) — a
+*   clear error, rather than being forwarded to the API as if it were base64.
+* - a string that isn't a URL — assumed to already be raw base64.
+*/
 async function imageToBase64(image) {
 	if (typeof image === "string") {
 		let url = null;
@@ -35,6 +50,7 @@ async function imageToBase64(image) {
 			if (!response.ok) throw new Error(`Failed to fetch image: ${response.status} ${response.statusText}`);
 			return blobToBase64(await response.blob());
 		}
+		if (url) throw new Error(`Unsupported image URL scheme: ${url.protocol}`);
 		return image;
 	}
 	return blobToBase64(image);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decartai/sdk",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "description": "Decart's JavaScript SDK",
   "type": "module",
   "license": "MIT",