@gradio/client 2.3.1 → 2.5.0

package/src/test/run_history.test.ts

@@ -0,0 +1,345 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+
+import {
+	clear_run_history,
+	consume_run_history_replay,
+	delete_run_history,
+	on_run_history_change,
+	read_run_history,
+	run_history_url,
+	stage_run_history_replay,
+	start_run_history,
+	update_run_history,
+	update_run_inputs
+} from "../utils/run_history";
+
+const app_id = "app-under-test";
+const other_app = "some-other-app";
+const scope = { app_id };
+const other_scope = { app_id: other_app };
+const replacement_apps = Array.from(
+	{ length: 8 },
+	(_, index) => `replacement-app-${index}`
+);
+const in_browser = typeof window !== "undefined";
+
+afterEach(() => {
+	clear_run_history(scope);
+	clear_run_history(other_scope);
+	for (const replacement_app of replacement_apps) {
+		clear_run_history({ app_id: replacement_app });
+	}
+	vi.useRealTimers();
+});
+
+describe.skipIf(!in_browser)("run history", () => {
+	test("stores runs per app id with the page and inputs", () => {
+		const id = start_run_history({
+			app_id,
+			endpoint: "/predict",
+			api_name: "/predict",
+			fn_index: 0,
+			inputs: ["hello"],
+			input_components: [
+				{
+					type: "textbox",
+					component_class_id: "textbox-id",
+					props: { label: "Prompt" }
+				}
+			]
+		});
+
+		const runs = read_run_history(scope);
+		expect(runs).toHaveLength(1);
+		expect(runs[0]).toMatchObject({
+			id,
+			endpoint: "/predict",
+			api_name: "/predict",
+			inputs: ["hello"],
+			status: "running",
+			input_components: [
+				{
+					type: "textbox",
+					component_class_id: "textbox-id",
+					props: { label: "Prompt" }
+				}
+			],
+			page: `${window.location.pathname}${window.location.search}`
+		});
+		expect(read_run_history(other_scope)).toEqual([]);
+	});
+
+	test("replaces inputs with their upload-processed values", () => {
+		const id = start_run_history({
+			app_id,
+			endpoint: "/predict",
+			api_name: "/predict",
+			fn_index: 0,
+			inputs: [new File(["hello"], "hello.txt")]
+		});
+
+		update_run_inputs(scope, id, [
+			{ path: "/tmp/hello.txt", url: "/gradio_api/file=/tmp/hello.txt" }
+		]);
+
+		expect(read_run_history(scope)[0].inputs).toEqual([
+			{ path: "/tmp/hello.txt", url: "/gradio_api/file=/tmp/hello.txt" }
+		]);
+	});
+
+	test("updates outputs and completion state", () => {
+		const id = start_run_history({
+			app_id,
+			endpoint: "/predict",
+			api_name: "/predict",
+			fn_index: 0,
+			inputs: ["hello"]
+		});
+
+		update_run_history(scope, id, {
+			type: "data",
+			endpoint: "/predict",
+			fn_index: 0,
+			data: ["hello hello"]
+		});
+		update_run_history(scope, id, {
+			type: "status",
+			endpoint: "/predict",
+			fn_index: 0,
+			queue: false,
+			stage: "complete",
+			time: new Date("2025-05-16T21:45:00Z")
+		});
+
+		expect(read_run_history(scope)[0]).toMatchObject({
+			outputs: ["hello hello"],
+			status: "completed",
+			completed_at: "2025-05-16T21:45:00.000Z"
+		});
+	});
+
+	test("records the runtime reported by the server", () => {
+		const id = start_run_history({
+			app_id,
+			endpoint: "/predict",
+			api_name: "/predict",
+			fn_index: 0,
+			inputs: ["hello"]
+		});
+
+		update_run_history(scope, id, {
+			type: "status",
+			endpoint: "/predict",
+			fn_index: 0,
+			queue: true,
+			stage: "complete",
+			cache_duration: 1.25,
+			time: new Date("2025-05-16T21:45:00Z")
+		});
+
+		expect(read_run_history(scope)[0]).toMatchObject({
+			duration_ms: 1250,
+			completed_at: "2025-05-16T21:45:00.000Z"
+		});
+	});
+
+	test("records failed runs and their error message", () => {
+		const id = start_run_history({
+			app_id,
+			endpoint: 3,
+			api_name: "Function 3",
+			fn_index: 3,
+			inputs: [{ circular: null }]
+		});
+
+		update_run_history(scope, id, {
+			type: "status",
+			endpoint: "/predict",
+			fn_index: 3,
+			queue: true,
+			stage: "error",
+			message: "generation failed"
+		});
+
+		expect(read_run_history(scope)[0]).toMatchObject({
+			status: "failed",
+			error: "generation failed"
+		});
+		expect(read_run_history(scope)[0].duration_ms).toBeGreaterThanOrEqual(0);
+	});
+
+	test("keeps only the newest 100 runs", () => {
+		for (let index = 0; index < 105; index++) {
+			start_run_history({
+				app_id,
+				endpoint: "/predict",
+				api_name: "/predict",
+				fn_index: 0,
+				inputs: [index]
+			});
+		}
+
+		const runs = read_run_history(scope);
+		expect(runs).toHaveLength(100);
+		expect(runs[0].inputs).toEqual([104]);
+		expect(runs.at(-1)?.inputs).toEqual([5]);
+	});
+
+	test("deletes an individual run", () => {
+		const first = start_run_history({
+			app_id,
+			endpoint: "/predict",
+			api_name: "/predict",
+			fn_index: 0,
+			inputs: ["first"]
+		});
+		start_run_history({
+			app_id,
+			endpoint: "/predict",
+			api_name: "/predict",
+			fn_index: 0,
+			inputs: ["second"]
+		});
+
+		delete_run_history(scope, first!);
+
+		expect(read_run_history(scope)).toHaveLength(1);
+		expect(read_run_history(scope)[0].inputs).toEqual(["second"]);
+	});
+
+	test("notifies this tab when runs are added, deleted or cleared", () => {
+		let notified = 0;
+		const unsubscribe = on_run_history_change(() => notified++);
+
+		const id = start_run_history({
+			app_id,
+			endpoint: "/predict",
+			api_name: "/predict",
+			fn_index: 0,
+			inputs: ["hello"]
+		});
+		expect(notified).toBe(1);
+
+		// Progress updates are not structural, so they must not notify.
+		update_run_history(scope, id, {
+			type: "status",
+			endpoint: "/predict",
+			fn_index: 0,
+			queue: true,
+			stage: "complete"
+		});
+		expect(notified).toBe(1);
+
+		delete_run_history(scope, id!);
+		expect(notified).toBe(2);
+
+		clear_run_history(scope);
+		expect(notified).toBe(3);
+
+		unsubscribe();
+		start_run_history({
+			app_id,
+			endpoint: "/predict",
+			api_name: "/predict",
+			fn_index: 0,
+			inputs: ["bye"]
+		});
+		expect(notified).toBe(3);
+	});
+
+	test("keeps a separate history per app id", () => {
+		start_run_history({
+			app_id,
+			endpoint: "/predict",
+			api_name: "/predict",
+			fn_index: 0,
+			inputs: ["mine"]
+		});
+		start_run_history({
+			app_id: other_app,
+			endpoint: "/predict",
+			api_name: "/predict",
+			fn_index: 0,
+			inputs: ["theirs"]
+		});
+
+		expect(read_run_history(scope)[0].inputs).toEqual(["mine"]);
+		expect(read_run_history(other_scope)[0].inputs).toEqual(["theirs"]);
+	});
+
+	test("keeps a separate history per user of the same app", () => {
+		const ada = { app_id, username: "ada" };
+		const grace = { app_id, username: "grace" };
+
+		start_run_history({
+			...ada,
+			endpoint: "/predict",
+			api_name: "/predict",
+			fn_index: 0,
+			inputs: ["ada's secret"]
+		});
+
+		expect(read_run_history(grace)).toEqual([]);
+		expect(read_run_history(scope)).toEqual([]);
+		expect(read_run_history(ada)[0].inputs).toEqual(["ada's secret"]);
+
+		clear_run_history(ada);
+	});
+
+	test("removes staged replays when pruning an old app", () => {
+		vi.useFakeTimers();
+		vi.setSystemTime(new Date("2025-01-01T00:00:00Z"));
+		start_run_history({
+			app_id: other_app,
+			endpoint: "/predict",
+			api_name: "/predict",
+			fn_index: 0,
+			inputs: ["old"]
+		});
+		stage_run_history_replay(other_scope, read_run_history(other_scope)[0]);
+
+		for (const [index, replacement_app] of replacement_apps.entries()) {
+			vi.setSystemTime(new Date(Date.UTC(2025, 0, index + 2)));
+			start_run_history({
+				app_id: replacement_app,
+				endpoint: "/predict",
+				api_name: "/predict",
+				fn_index: 0,
+				inputs: [index]
+			});
+		}
+
+		expect(read_run_history(other_scope)).toEqual([]);
+		expect(consume_run_history_replay(other_scope)).toBeNull();
+	});
+});
+
+describe("run history url", () => {
+	test("joins the app root and the api prefix", () => {
+		expect(run_history_url("http://localhost:7860")).toBe(
+			"http://localhost:7860/gradio_api/runs"
+		);
+		expect(run_history_url("http://localhost:7860/my-app/")).toBe(
+			"http://localhost:7860/my-app/gradio_api/runs"
+		);
+		expect(run_history_url("http://localhost:7860", "/api")).toBe(
+			"http://localhost:7860/api/runs"
+		);
+	});
+});
+
+describe.skipIf(in_browser)("run history outside the browser", () => {
+	test("is a no-op without storage", () => {
+		expect(
+			start_run_history({
+				app_id,
+				endpoint: "/predict",
+				api_name: "/predict",
+				fn_index: 0,
+				inputs: ["hello"]
+			})
+		).toBeNull();
+		expect(read_run_history(scope)).toEqual([]);
+		expect(consume_run_history_replay(scope)).toBeNull();
+	});
+});

package/src/test/submit.test.ts

@@ -162,8 +162,6 @@ describe("predict error handling", () => {
 				1000,
 				"predict() never settled for an unknown endpoint"
 			)
-		).rejects.toThrow(
-			"There is no endpoint matching that name of fn_index matching that number."
-		);
+		).rejects.toThrow('No endpoint matching "nonexistent_endpoint" was found');
 	});
 });

package/src/types.ts

@@ -36,6 +36,8 @@ export interface EndpointInfo<T extends ApiData | JsApiData> {
 	parameters: T[];
 	returns: T[];
 	type?: DependencyTypes;
+	/** Set when the endpoint's function takes a `gr.OAuthToken`. */
+	oauth_token?: "required" | "optional";
 }
 
 export interface ApiInfo<T extends ApiData | JsApiData> {
@@ -209,6 +211,12 @@ export interface Config {
 	pwa?: boolean;
 	i18n_translations?: Record<string, Record<string, string>> | null;
 	mcp_server?: boolean;
+	/**
+	 * Whether the app permits its runs being saved in the browser. Set from
+	 * `run_history` on `launch()`; absent on apps served by older versions of
+	 * Gradio, which is treated as permitted.
+	 */
+	run_history?: boolean;
 }
 
 // todo: DRY up types
@@ -301,6 +309,7 @@ export interface Payload {
 	time?: Date;
 	event_data?: unknown;
 	trigger_id?: number | null;
+	oauth_token?: string;
 }
 
 export interface PostResponse {
@@ -323,6 +332,11 @@ export interface DuplicateOptions extends ClientOptions {
 
 export interface ClientOptions {
 	token?: `hf_${string}`;
+	/**
+	 * @deprecated Use `token` instead. Kept as an alias so that code written
+	 * for older versions of the client keeps working.
+	 */
+	hf_token?: `hf_${string}`;
 	status_callback?: SpaceStatusCallback | null;
 	auth?: [string, string] | null;
 	with_null_state?: boolean;
@@ -332,6 +346,21 @@ export interface ClientOptions {
 	session_hash?: string;
 	cookies?: string;
 	credentials?: RequestCredentials;
+	/**
+	 * A Hugging Face token passed to the app's own code, for endpoints whose
+	 * function takes a `gr.OAuthToken`. Unlike `token`, which only authenticates
+	 * you to the app, this lets the app act on your behalf, so it is sent only to
+	 * endpoints that declare they need it.
+	 */
+	oauth_token?: string;
+	/**
+	 * Whether to save each call's inputs and outputs in this browser's local
+	 * storage, so they can be reviewed on the app's run history page. Defaults
+	 * to true, and only ever applies in a browser: in Node there is no storage
+	 * to write to and nothing is recorded. The app can turn it off for everyone
+	 * with `run_history=False` on `launch()`, which takes precedence over this.
+	 */
+	record_history?: boolean;
 }
 
 export interface FileData {

package/src/utils/duplicate.ts

@@ -8,6 +8,7 @@ import { Client } from "../client";
 import { SPACE_METADATA_ERROR_MSG } from "../constants";
 import {
 	get_cookie_header,
+	normalise_token_option,
 	parse_and_set_cookies
 } from "../helpers/init_helpers";
 import { process_endpoint } from "../helpers/api_info";
@@ -16,6 +17,7 @@ export async function duplicate(
 	app_reference: string,
 	options: DuplicateOptions
 ): Promise<Client> {
+	normalise_token_option(options);
 	const { token, private: _private, hardware, timeout, auth } = options;
 
 	if (hardware && !hardware_types.includes(hardware)) {

package/src/utils/predict.ts

@@ -37,7 +37,20 @@ export async function predict<T = unknown>(
 
 		if (message.type === "status") {
 			if (message.stage === "error") {
-				throw message;
+				// Throw a real `Error` (rather than the raw status object) so that
+				// uncaught failures surface a readable message instead of
+				// crashing Node with `ERR_UNHANDLED_REJECTION ... reason "#<Object>"`.
+				// The status fields are preserved on the error for callers that
+				// inspect them.
+				const { message: error_message, ...status } = message;
+				const error = new Error(
+					(typeof error_message === "string"
+						? error_message
+						: error_message && JSON.stringify(error_message)) ||
+						"An unknown error occurred while making a prediction."
+				);
+				Object.assign(error, status);
+				throw error;
 			}
 			if (message.stage === "complete") {
 				status_complete = true;