@classytic/arc-next 0.4.1 → 0.5.0

package/dist/sse.d.ts

@@ -1,69 +1,148 @@
 import { QueryKey } from "@tanstack/react-query";
 
 //#region src/sse.d.ts
-interface ArcServerEvent {
+/**
+ * Build an authenticated SSE URL using the global client + auth singletons.
+ *
+ * Thin alias for {@link import('./client.js').buildStreamUrl} with the HTTP
+ * protocol — kept as a named export so SSE consumers don't have to think about
+ * the `protocol` arg.
+ *
+ * @example
+ * const es = new EventSource(buildSseUrl('/jobs/stream', { jobId }), {
+ *   withCredentials: getAuthMode() === 'cookie',
+ * });
+ */
+declare function buildSseUrl(path: string, params?: Record<string, string | number | boolean | null | undefined>): string;
+/**
+ * Generic Arc server event envelope.
+ *
+ * Defaults to `unknown` payload — narrow with the generic when you control
+ * the broadcast shape (`ArcServerEvent<Todo>`). For the canonical CRUD shape,
+ * use {@link CrudEvent} which constrains `type` to `<resource>.<operation>`
+ * and `operation` to the three lifecycle verbs.
+ */
+interface ArcServerEvent<TData = unknown> {
   type: string;
   resource: string;
-  data: unknown;
+  data: TData;
   timestamp: string;
   id?: string;
 }
-interface EventStreamOptions {
-  /** Full SSE endpoint URL. When set, overrides `path` and `baseUrl`. Use for non-Arc backends or custom URLs. */
+/** Lifecycle operations Arc emits on every CRUD broadcast. */
+type CrudOperation = "created" | "updated" | "deleted";
+/**
+ * Typed CRUD event narrowed to Arc's `<resource>.<operation>` envelope.
+ *
+ * Arc auto-emits this shape from `BaseController` for every list/get/create/
+ * update/delete. Pass `<TDoc>` so SSE/WS callbacks get inference for free:
+ *
+ * ```ts
+ * subscribeToEvents<CrudEvent<Todo>>({
+ *   resource: 'todo',
+ *   onEvent: (e) => console.log(e.operation, e.data.title),
+ * });
+ * ```
+ */
+interface CrudEvent<TDoc = unknown> extends ArcServerEvent<TDoc> {
+  /** Always `<resource>.<operation>` (e.g. `'todo.created'`). */
+  type: string;
+  operation: CrudOperation;
+}
+interface SubscribeToEventsOptions<TData = unknown> {
+  /** Full SSE endpoint URL. When set, overrides `path` and `baseUrl`. */
   url?: string;
-  /**
-   * Resource name for automatic pattern filtering.
-   * When set and `patterns` is empty, auto-generates `['resource.*']` filter.
-   * Does NOT affect the endpoint URL — use `path` for that.
-   */
+  /** Resource name for auto pattern filtering + named-event derivation. */
   resource?: string;
-  /**
-   * SSE endpoint path (appended to baseUrl). Default: '/events/stream'.
-   * Matches Arc's ssePlugin default. Override if your backend uses a custom path.
-   */
+  /** Endpoint path (default: `/events/stream`). */
   path?: string;
-  /** Event patterns to listen for (e.g., ['agents.created', 'agents.updated']). When empty, all events are received. */
+  /** Event patterns to listen for (e.g. `['todo.*']`). Empty → all events. */
   patterns?: string[];
-  /** Query keys to invalidate when any event is received. */
-  invalidateQueries?: QueryKey[];
-  /** Callback for each event. */
-  onEvent?: (event: ArcServerEvent) => void;
-  /** Callback for connection state changes. */
+  /**
+   * Named SSE event types to subscribe to via `addEventListener`.
+   * Falls back to `patterns` (literal entries) or `[<resource>.created|updated|deleted]`.
+   * Pass `[]` to opt out of named-event subscription entirely.
+   */
+  eventTypes?: string[];
+  /** Per-event callback. */
+  onEvent?: (event: ArcServerEvent<TData>) => void;
+  /** Connection-state callback. */
   onConnectionChange?: (connected: boolean) => void;
-  /** Whether the stream is enabled. Default: true */
-  enabled?: boolean;
-  /** Reconnect delay in ms. Default: 3000 */
+  /** Reconnect delay in ms. Default: 3000. */
   reconnectDelay?: number;
-  /** Maximum reconnect attempts before giving up. Default: Infinity */
+  /** Maximum reconnect attempts. Default: Infinity. */
   maxReconnectAttempts?: number;
   /** Whether to include credentials (cookies). Derived from authMode when not set. */
   withCredentials?: boolean;
 }
-interface EventStreamResult {
-  /** Whether the EventSource is currently connected. */
+/** Handle returned by {@link subscribeToEvents}. Stable across reconnects. */
+interface SubscribeToEventsHandle {
+  close: () => void;
+  reconnect: () => void;
+  isConnected: () => boolean;
+}
+interface EventStreamOptions<TData = unknown> extends SubscribeToEventsOptions<TData> {
+  /** Query keys to invalidate when any matching event arrives. */
+  invalidateQueries?: QueryKey[];
+  /** Whether the stream is active. Default: true. */
+  enabled?: boolean;
+  /**
+   * Whether to track `lastEvent` in React state. Default: true.
+   *
+   * Set to `false` for high-volume streams (telemetry, live tickers) where
+   * the consumer uses `onEvent` for fire-and-forget handling and never reads
+   * `result.lastEvent`. Each inbound frame skips a `setState` call,
+   * eliminating per-event re-renders.
+   */
+  trackLastEvent?: boolean;
+  /**
+   * Whether to track `eventCount` in React state. Default: true.
+   *
+   * Same trade-off as `trackLastEvent`: skip the counter `setState` for
+   * high-volume streams that don't read it.
+   */
+  trackEventCount?: boolean;
+}
+interface EventStreamResult<TData = unknown> {
   isConnected: boolean;
-  /** The most recently received event. */
-  lastEvent: ArcServerEvent | null;
-  /** Number of events received since connection. */
+  lastEvent: ArcServerEvent<TData> | null;
   eventCount: number;
-  /** Close the connection manually. */
   close: () => void;
-  /** Reconnect after a manual close. */
   reconnect: () => void;
 }
+/**
+ * Subscribe to an Arc SSE stream from any JS context (React, Node, Bun, tests).
+ * Pure function — no React hook required. Returns a handle with `close()` /
+ * `reconnect()` / `isConnected()`.
+ *
+ * Reconnect uses exponential backoff (×1.5 per attempt, capped at 30s).
+ * Subscriptions persist across reconnect.
+ *
+ * @example
+ * const sub = subscribeToEvents<CrudEvent<Todo>>({
+ *   resource: 'todo',
+ *   onEvent: (e) => console.log(e.operation, e.data.title),
+ * });
+ * // ...later
+ * sub.close();
+ */
+declare function subscribeToEvents<TData = unknown>(options: SubscribeToEventsOptions<TData>): SubscribeToEventsHandle;
 /**
  * Subscribe to Arc server-sent events for real-time cache invalidation.
  *
- * Uses the browser's native `EventSource` API for automatic reconnection
+ * Uses the browser's native `EventSource` for automatic reconnection
  * and efficient server-push. Events trigger query invalidation so TanStack Query
  * refetches affected data automatically.
  *
+ * Internally delegates to {@link subscribeToEvents} — for non-React contexts
+ * (Node, tests, plain JS) call that directly.
+ *
  * @example
- * const { isConnected } = useEventStream({
- *   resource: 'agents',
- *   invalidateQueries: [agentKeys.lists()],
+ * const { isConnected } = useEventStream<CrudEvent<Todo>>({
+ *   resource: 'todo',
+ *   invalidateQueries: [todoKeys.lists()],
  * });
  */
-declare function useEventStream(options: EventStreamOptions): EventStreamResult;
+declare function useEventStream<TData = unknown>(options: EventStreamOptions<TData>): EventStreamResult<TData>;
 //#endregion
-export { ArcServerEvent, EventStreamOptions, EventStreamResult, useEventStream };
+export { ArcServerEvent, CrudEvent, CrudOperation, EventStreamOptions, EventStreamResult, SubscribeToEventsHandle, SubscribeToEventsOptions, buildSseUrl, subscribeToEvents, useEventStream };

package/dist/sse.js

@@ -1,145 +1,221 @@
 "use client";
 
-import { getAuthContext, getAuthMode, getBaseUrl } from "./client.js";
+import { buildStreamUrl, getAuthMode } from "./client.js";
 import { useQueryClient } from "@tanstack/react-query";
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 
 //#region src/sse.ts
 /**
+* Build an authenticated SSE URL using the global client + auth singletons.
+*
+* Thin alias for {@link import('./client.js').buildStreamUrl} with the HTTP
+* protocol — kept as a named export so SSE consumers don't have to think about
+* the `protocol` arg.
+*
+* @example
+* const es = new EventSource(buildSseUrl('/jobs/stream', { jobId }), {
+*   withCredentials: getAuthMode() === 'cookie',
+* });
+*/
+function buildSseUrl(path, params = {}) {
+	return buildStreamUrl(path, params, "http");
+}
+/**
+* Subscribe to an Arc SSE stream from any JS context (React, Node, Bun, tests).
+* Pure function — no React hook required. Returns a handle with `close()` /
+* `reconnect()` / `isConnected()`.
+*
+* Reconnect uses exponential backoff (×1.5 per attempt, capped at 30s).
+* Subscriptions persist across reconnect.
+*
+* @example
+* const sub = subscribeToEvents<CrudEvent<Todo>>({
+*   resource: 'todo',
+*   onEvent: (e) => console.log(e.operation, e.data.title),
+* });
+* // ...later
+* sub.close();
+*/
+function subscribeToEvents(options) {
+	const { url, resource, path: ssePath = "/events/stream", patterns = [], reconnectDelay = 3e3, maxReconnectAttempts = Infinity, withCredentials } = options;
+	let es = null;
+	let reconnectAttempts = 0;
+	let reconnectTimer = null;
+	let manualClose = false;
+	let connected = false;
+	const resolvedEventTypes = options.eventTypes !== void 0 ? options.eventTypes : patterns.length > 0 ? patterns.filter((p) => !p.includes("*")) : resource ? [
+		`${resource}.created`,
+		`${resource}.updated`,
+		`${resource}.deleted`
+	] : [];
+	const buildUrl = () => {
+		if (url) return url;
+		const effectivePatterns = patterns.length > 0 ? patterns : resource ? [`${resource}.*`] : [];
+		const params = {};
+		if (effectivePatterns.length > 0) params.patterns = effectivePatterns.join(",");
+		return buildSseUrl(ssePath, params);
+	};
+	const dispatch = (parsed) => {
+		if (patterns.length > 0 && !patterns.includes(parsed.type)) return;
+		options.onEvent?.(parsed);
+	};
+	const connect = () => {
+		if (es) try {
+			es.close();
+		} catch {}
+		manualClose = false;
+		const credentials = withCredentials ?? getAuthMode() === "cookie";
+		es = new EventSource(buildUrl(), { withCredentials: credentials });
+		es.onopen = () => {
+			reconnectAttempts = 0;
+			connected = true;
+			options.onConnectionChange?.(true);
+		};
+		es.onmessage = (event) => {
+			try {
+				dispatch(JSON.parse(event.data));
+			} catch {}
+		};
+		for (const eventType of resolvedEventTypes) es.addEventListener(eventType, (event) => {
+			let payload;
+			try {
+				payload = JSON.parse(event.data);
+			} catch {
+				payload = event.data;
+			}
+			dispatch(typeof payload === "object" && payload !== null && "type" in payload && "data" in payload ? payload : {
+				type: eventType,
+				resource: resource ?? eventType.split(".")[0] ?? "",
+				data: payload,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+				...event.lastEventId ? { id: event.lastEventId } : {}
+			});
+		});
+		es.onerror = () => {
+			try {
+				es?.close();
+			} catch {}
+			connected = false;
+			options.onConnectionChange?.(false);
+			if (manualClose) return;
+			if (reconnectAttempts < maxReconnectAttempts) {
+				reconnectAttempts += 1;
+				const delay = Math.min(reconnectDelay * Math.pow(1.5, reconnectAttempts - 1), 3e4);
+				reconnectTimer = setTimeout(connect, delay);
+			}
+		};
+	};
+	connect();
+	return {
+		close: () => {
+			manualClose = true;
+			if (reconnectTimer) {
+				clearTimeout(reconnectTimer);
+				reconnectTimer = null;
+			}
+			if (es) {
+				try {
+					es.close();
+				} catch {}
+				es = null;
+			}
+			connected = false;
+			options.onConnectionChange?.(false);
+		},
+		reconnect: () => {
+			reconnectAttempts = 0;
+			manualClose = false;
+			connect();
+		},
+		isConnected: () => connected
+	};
+}
+/**
 * Subscribe to Arc server-sent events for real-time cache invalidation.
 *
-* Uses the browser's native `EventSource` API for automatic reconnection
+* Uses the browser's native `EventSource` for automatic reconnection
 * and efficient server-push. Events trigger query invalidation so TanStack Query
 * refetches affected data automatically.
 *
+* Internally delegates to {@link subscribeToEvents} — for non-React contexts
+* (Node, tests, plain JS) call that directly.
+*
 * @example
-* const { isConnected } = useEventStream({
-*   resource: 'agents',
-*   invalidateQueries: [agentKeys.lists()],
+* const { isConnected } = useEventStream<CrudEvent<Todo>>({
+*   resource: 'todo',
+*   invalidateQueries: [todoKeys.lists()],
 * });
 */
 function useEventStream(options) {
-	const { url, resource, path: ssePath = "/events/stream", enabled = true, reconnectDelay = 3e3, maxReconnectAttempts = Infinity, withCredentials } = options;
+	const { url, resource, path, enabled = true, trackLastEvent = true, trackEventCount = true } = options;
 	const queryClient = useQueryClient();
 	const [isConnected, setIsConnected] = useState(false);
 	const [lastEvent, setLastEvent] = useState(null);
 	const [eventCount, setEventCount] = useState(0);
-	const esRef = useRef(null);
-	const reconnectAttemptsRef = useRef(0);
-	const reconnectTimerRef = useRef(null);
-	const manualCloseRef = useRef(false);
+	const handleRef = useRef(null);
 	const onEventRef = useRef(options.onEvent);
 	onEventRef.current = options.onEvent;
 	const onConnectionChangeRef = useRef(options.onConnectionChange);
 	onConnectionChangeRef.current = options.onConnectionChange;
-	const patternsRef = useRef(options.patterns ?? []);
-	patternsRef.current = options.patterns ?? [];
 	const invalidateKeysRef = useRef(options.invalidateQueries ?? []);
 	invalidateKeysRef.current = options.invalidateQueries ?? [];
-	const buildUrl = useCallback(() => {
-		if (url) return url;
-		const auth = getAuthContext();
-		const params = new URLSearchParams();
-		const patterns = patternsRef.current;
-		const effectivePatterns = patterns.length > 0 ? patterns : resource ? [`${resource}.*`] : [];
-		if (effectivePatterns.length > 0) params.set("patterns", effectivePatterns.join(","));
-		if (auth.organizationId) params.set("organizationId", auth.organizationId);
-		if (auth.token) params.set("token", auth.token);
-		const qs = params.toString();
-		const base = `${getBaseUrl()}${ssePath}`;
-		return qs ? `${base}?${qs}` : base;
-	}, [
-		url,
-		resource,
-		ssePath
-	]);
-	const connect = useCallback(() => {
-		if (esRef.current) esRef.current.close();
-		manualCloseRef.current = false;
-		const eventUrl = buildUrl();
-		const authMode = getAuthMode();
-		const es = new EventSource(eventUrl, { withCredentials: withCredentials ?? authMode === "cookie" });
-		esRef.current = es;
-		es.onopen = () => {
-			reconnectAttemptsRef.current = 0;
-			setIsConnected(true);
-			onConnectionChangeRef.current?.(true);
-		};
-		es.onmessage = (event) => {
-			try {
-				const parsed = JSON.parse(event.data);
-				const patterns = patternsRef.current;
-				if (patterns.length > 0 && !patterns.includes(parsed.type)) return;
-				setLastEvent(parsed);
-				setEventCount((c) => c + 1);
-				onEventRef.current?.(parsed);
-				const keys = invalidateKeysRef.current;
-				for (const key of keys) queryClient.invalidateQueries({ queryKey: key });
-			} catch {}
-		};
-		es.onerror = () => {
-			es.close();
-			setIsConnected(false);
-			onConnectionChangeRef.current?.(false);
-			if (manualCloseRef.current) return;
-			if (reconnectAttemptsRef.current < maxReconnectAttempts) {
-				reconnectAttemptsRef.current += 1;
-				const delay = Math.min(reconnectDelay * Math.pow(1.5, reconnectAttemptsRef.current - 1), 3e4);
-				reconnectTimerRef.current = setTimeout(connect, delay);
-			}
-		};
-	}, [
-		buildUrl,
-		queryClient,
-		withCredentials,
-		reconnectDelay,
-		maxReconnectAttempts
-	]);
-	const close = useCallback(() => {
-		manualCloseRef.current = true;
-		if (reconnectTimerRef.current) {
-			clearTimeout(reconnectTimerRef.current);
-			reconnectTimerRef.current = null;
-		}
-		if (esRef.current) {
-			esRef.current.close();
-			esRef.current = null;
-		}
-		setIsConnected(false);
-		onConnectionChangeRef.current?.(false);
-	}, []);
-	const reconnect = useCallback(() => {
-		reconnectAttemptsRef.current = 0;
-		manualCloseRef.current = false;
-		connect();
-	}, [connect]);
+	const patternsKey = JSON.stringify(options.patterns ?? null);
+	const eventTypesKey = JSON.stringify(options.eventTypes ?? null);
+	const patterns = useMemo(() => options.patterns, [patternsKey]);
+	const eventTypes = useMemo(() => options.eventTypes, [eventTypesKey]);
 	useEffect(() => {
 		if (!enabled) {
-			close();
+			handleRef.current?.close();
+			handleRef.current = null;
 			return;
 		}
-		connect();
-		return () => {
-			manualCloseRef.current = true;
-			if (reconnectTimerRef.current) clearTimeout(reconnectTimerRef.current);
-			if (esRef.current) {
-				esRef.current.close();
-				esRef.current = null;
+		const handle = subscribeToEvents({
+			url,
+			resource,
+			path,
+			patterns,
+			eventTypes,
+			reconnectDelay: options.reconnectDelay,
+			maxReconnectAttempts: options.maxReconnectAttempts,
+			withCredentials: options.withCredentials,
+			onConnectionChange: (c) => {
+				setIsConnected(c);
+				onConnectionChangeRef.current?.(c);
+			},
+			onEvent: (event) => {
+				if (trackLastEvent) setLastEvent(event);
+				if (trackEventCount) setEventCount((n) => n + 1);
+				onEventRef.current?.(event);
+				for (const key of invalidateKeysRef.current) queryClient.invalidateQueries({ queryKey: key });
 			}
+		});
+		handleRef.current = handle;
+		return () => {
+			handle.close();
+			handleRef.current = null;
 		};
 	}, [
 		enabled,
-		connect,
-		close
+		url,
+		resource,
+		path,
+		patterns,
+		eventTypes,
+		options.reconnectDelay,
+		options.maxReconnectAttempts,
+		options.withCredentials,
+		trackLastEvent,
+		trackEventCount,
+		queryClient
 	]);
 	return {
 		isConnected,
 		lastEvent,
 		eventCount,
-		close,
-		reconnect
+		close: () => handleRef.current?.close(),
+		reconnect: () => handleRef.current?.reconnect()
 	};
 }
 
 //#endregion
-export { useEventStream };
+export { buildSseUrl, subscribeToEvents, useEventStream };

package/dist/upload.d.ts

@@ -0,0 +1,181 @@
+import { ArcClient, HttpMethod, ToastHandler } from "./client.js";
+import { MutationMessages } from "./mutation.js";
+import { QueryKey } from "@tanstack/react-query";
+
+//#region src/upload.d.ts
+/**
+ * Upload-progress snapshot. Emitted on every native `xhr.upload.progress`
+ * event. `lengthComputable` reflects whether the browser knows the total —
+ * always true for `FormData` bodies in modern browsers, but consumers MUST
+ * check it before treating `percent` as meaningful (some embedded WebView
+ * environments still emit non-computable progress).
+ */
+interface UploadProgress {
+  /** 0..100, integer-rounded. Equal to `(loaded / total) * 100` when computable, 0 otherwise. */
+  percent: number;
+  /** Bytes successfully uploaded so far. */
+  loaded: number;
+  /** Total bytes the request body announces. 0 when `lengthComputable` is false. */
+  total: number;
+  /** Whether the runtime knows the total. False ⇒ `percent` is 0 and not meaningful. */
+  lengthComputable: boolean;
+}
+interface UploadWithProgressOptions {
+  /**
+   * Target endpoint. Absolute (`https://api.example.com/...`) or relative
+   * (`/api/v1/media/upload`). Relative paths are prefixed with the configured
+   * `baseUrl` from `configureClient()` (or `client.config.baseUrl`).
+   */
+  url: string;
+  /**
+   * Request body. Pass `FormData` directly — XHR auto-sets the
+   * `multipart/form-data` Content-Type with the right boundary. We never set
+   * Content-Type ourselves on FormData uploads; doing so strips the boundary.
+   */
+  formData: FormData;
+  /** HTTP method. Default: `'POST'`. */
+  method?: HttpMethod;
+  /** Per-event progress callback. Called on every `xhr.upload.progress`. */
+  onProgress?: (progress: UploadProgress) => void;
+  /**
+   * Abort signal. When the signal fires (or is already aborted), the XHR is
+   * aborted immediately and the returned promise rejects with the signal's
+   * `reason` (or `DOMException('AbortError')` if no reason was set).
+   */
+  signal?: AbortSignal;
+  /**
+   * Per-client auth context override. When provided, auth headers
+   * (`Authorization`, `x-organization-id`, `x-arc-scope`) and `withCredentials`
+   * are derived from this client's config. Falls back to the global
+   * `configureClient()` / `configureAuth()` singletons when absent.
+   */
+  client?: ArcClient;
+  /** Explicit token, overrides `client?.auth?.getToken()` and global. */
+  token?: string | null;
+  /** Explicit organization id, overrides `client?.auth?.getOrgId()` and global. */
+  organizationId?: string | null;
+  /**
+   * Extra headers merged on top of the auth-derived headers. Use for
+   * per-request needs (`Accept-Version`, `x-foo`, etc.). Setting
+   * `Content-Type` here is allowed but discouraged — XHR computes the
+   * multipart boundary automatically.
+   */
+  headers?: Record<string, string>;
+  /** Send `x-arc-scope: platform` for arc's elevated-scope upgrade. */
+  elevated?: boolean;
+  /** Sent as `Idempotency-Key` header. Match the fetch path's contract. */
+  idempotencyKey?: string;
+  /**
+   * Treat the response as a binary blob instead of attempting JSON parse.
+   * Use when the upload returns a transformed file (e.g. the server resizes
+   * an image and returns the resized binary). Default: false (parse JSON).
+   */
+  responseType?: "json" | "text" | "blob";
+}
+/**
+ * Upload a `FormData` payload via XHR with native progress events.
+ *
+ * Returns a Promise that resolves with the parsed response body
+ * (`responseType: 'json'` by default — pass `'text'` or `'blob'` to opt out).
+ * Rejects with {@link ArcApiError} on non-2xx, with abort errors when the
+ * provided signal fires, or `Error` on transport failure (network down, CORS).
+ *
+ * Reuses {@link getClientAuthContext} so the global `configureAuth()` token /
+ * orgId — and per-client overrides via `client?.auth` — flow through. Sets
+ * `withCredentials = true` automatically for `authMode: 'cookie'`.
+ *
+ * @example
+ * const result = await uploadWithProgress<{ url: string }>({
+ *   url: '/api/v1/media/upload',
+ *   formData,
+ *   onProgress: ({ percent }) => setUiProgress(percent),
+ * });
+ */
+declare function uploadWithProgress<TResult = unknown>(options: UploadWithProgressOptions): Promise<TResult>;
+interface UseUploadWithProgressOptions<TResult, TVars> {
+  /** Endpoint URL or a function that derives it from `vars`. Relative or absolute. */
+  url: string | ((vars: TVars) => string);
+  /** HTTP method. Default: `'POST'`. */
+  method?: HttpMethod;
+  /** Build the FormData payload from the call's variables. */
+  buildFormData: (vars: TVars) => FormData;
+  /** Query keys to invalidate after a successful upload. */
+  invalidateQueries?: QueryKey[];
+  /** Toast messages. Same shape as `useMutationWithTransition`. */
+  messages?: MutationMessages;
+  /** Override the global toast handler for this hook only. */
+  toastHandler?: ToastHandler;
+  /** Per-client auth pipeline (multi-backend apps). */
+  client?: ArcClient;
+  /**
+   * Extra request headers per call. Function form receives the call's vars
+   * so you can compute headers from the upload (e.g. an idempotency key
+   * derived from the file hash).
+   */
+  headers?: Record<string, string> | ((vars: TVars) => Record<string, string>);
+  /** Send `x-arc-scope: platform`. Per-call dynamic via function form. */
+  elevated?: boolean | ((vars: TVars) => boolean);
+  /** Per-call idempotency key. Function form gets the vars. */
+  idempotencyKey?: string | ((vars: TVars) => string);
+  /** `'json'` (default), `'text'`, or `'blob'`. */
+  responseType?: "json" | "text" | "blob";
+  onSuccess?: (data: TResult, vars: TVars) => void;
+  onError?: (error: Error, vars: TVars) => void;
+  onSettled?: (data: TResult | undefined, error: Error | null, vars: TVars) => void;
+  /** Per-event progress callback (in addition to the React state mirror). */
+  onProgress?: (progress: UploadProgress, vars: TVars) => void;
+}
+interface UseUploadWithProgressResult<TResult, TVars> {
+  /**
+   * Trigger an upload. Returns a Promise that resolves with the parsed
+   * response body or rejects with `ArcApiError` / abort error.
+   */
+  upload: (vars: TVars) => Promise<TResult>;
+  /** Latest progress snapshot. Null when no upload is active. */
+  progress: UploadProgress | null;
+  /** True from `upload()` start until resolve/reject/cancel. */
+  isUploading: boolean;
+  /** Alias for `isUploading` — matches TanStack mutation naming. */
+  isPending: boolean;
+  /** Last-resolved data (kept across calls until `reset()` or next upload). */
+  data: TResult | null;
+  /** Last error (cleared on the next upload or `reset()`). */
+  error: Error | null;
+  /** Whether the last upload succeeded. */
+  isSuccess: boolean;
+  /** Whether the last upload errored. */
+  isError: boolean;
+  /** Abort the in-flight upload. No-op when none is active. */
+  cancel: () => void;
+  /** Clear progress / data / error so the hook reads as "idle" again. */
+  reset: () => void;
+}
+/**
+ * React hook that wraps {@link uploadWithProgress} with TanStack-Query-style
+ * mutation ergonomics. Progress lives in React state — every progress tick
+ * re-renders the consumer so binding `progress.percent` to a `<ProgressBar>`
+ * "just works" with no extra plumbing.
+ *
+ * @example
+ * const { upload, progress, isUploading, cancel, error } = useUploadWithProgress<
+ *   { url: string }[],
+ *   { files: File[]; folder?: string }
+ * >({
+ *   url: '/api/v1/media/upload-multiple',
+ *   buildFormData: ({ files, folder }) => {
+ *     const fd = new FormData();
+ *     if (folder) fd.append('folder', folder);
+ *     files.forEach((f) => fd.append('files[]', f));
+ *     return fd;
+ *   },
+ *   invalidateQueries: [mediaKeys.lists()],
+ *   messages: { success: 'Uploaded', error: 'Upload failed' },
+ * });
+ *
+ * <ProgressBar value={progress?.percent ?? 0} />
+ * <button onClick={() => upload({ files })}>Upload</button>
+ * {isUploading && <button onClick={cancel}>Cancel</button>}
+ */
+declare function useUploadWithProgress<TResult = unknown, TVars = unknown>(options: UseUploadWithProgressOptions<TResult, TVars>): UseUploadWithProgressResult<TResult, TVars>;
+//#endregion
+export { UploadProgress, UploadWithProgressOptions, UseUploadWithProgressOptions, UseUploadWithProgressResult, uploadWithProgress, useUploadWithProgress };