@transloadit/convex 0.0.2 → 0.0.4

package/dist/react/index.js

@@ -1,76 +1,201 @@
+import { isAssemblyTerminal, } from "@transloadit/zod/v3/assemblyStatus";
 import { useAction, useQuery } from "convex/react";
-import { useCallback, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Upload } from "tus-js-client";
-async function uploadViaForm(file, params, options) {
-    const formData = new FormData();
-    formData.append("params", params.params);
-    formData.append("signature", params.signature);
-    formData.append(options.fileField ?? "file", file);
-    return new Promise((resolve, reject) => {
-        const xhr = new XMLHttpRequest();
-        xhr.open("POST", params.url, true);
-        xhr.upload.onprogress = (event) => {
-            if (!event.lengthComputable)
-                return;
-            const progress = Math.round((event.loaded / event.total) * 100);
-            options.onProgress?.(progress);
+import { getAssemblyStage, parseAssemblyStatus, } from "../shared/assemblyUrls.js";
+import { transloaditError } from "../shared/errors.js";
+import { pollAssembly } from "../shared/pollAssembly.js";
+import { buildTusUploadConfig } from "../shared/tusUpload.js";
+export async function uploadWithAssembly(createAssembly, uppy, options) {
+    const files = uppy.getFiles();
+    if (files.length === 0) {
+        throw transloaditError("upload", "No files provided for upload");
+    }
+    const args = {
+        ...(options.createAssemblyArgs ?? {}),
+        fileCount: options.fileCount ?? files.length,
+    };
+    const assembly = await createAssembly(args);
+    options.onAssemblyCreated?.(assembly);
+    const tusPlugin = uppy.getPlugin("Tus");
+    if (!tusPlugin) {
+        throw transloaditError("upload", 'Uppy Tus plugin is required. Call uppy.use(Tus, { endpoint: "" }) before uploadWithAssembly.');
+    }
+    let tusEndpoint = null;
+    const addRequestId = options.addRequestId ?? true;
+    for (const file of files) {
+        if (!file.data ||
+            typeof Blob === "undefined" ||
+            !(file.data instanceof Blob)) {
+            throw transloaditError("upload", "Uppy file is missing binary data for upload");
+        }
+        const uploadFile = file.data instanceof File
+            ? file.data
+            : new File([file.data], file.name ?? "file", {
+                type: file.data.type || file.type,
+            });
+        const { endpoint, metadata } = buildTusUploadConfig(assembly.data, uploadFile, {
+            fieldName: options.fieldName,
+            metadata: options.metadata,
+        });
+        if (!tusEndpoint) {
+            tusEndpoint = endpoint;
+        }
+        uppy.setFileMeta(file.id, metadata);
+        uppy.setFileState(file.id, {
+            tus: {
+                ...(file.tus ?? {}),
+                endpoint,
+                addRequestId,
+            },
+        });
+    }
+    if (tusPlugin && "setOptions" in tusPlugin && tusEndpoint) {
+        tusPlugin.setOptions?.({ endpoint: tusEndpoint, addRequestId });
+    }
+    const uploadResult = await uppy.upload();
+    if (!uploadResult) {
+        throw transloaditError("upload", "Uppy upload did not return a result");
+    }
+    return { assembly, uploadResult };
+}
+/**
+ * Low-level tus upload helper. Prefer `useTransloaditUpload` for new code.
+ */
+/**
+ * Low-level tus upload helper. Prefer `useTransloaditUpload` for new code.
+ */
+export async function uploadWithTransloaditTus(createAssembly, file, options, events = {}) {
+    let currentState = {
+        isUploading: true,
+        progress: 0,
+        error: null,
+    };
+    const emitState = (next) => {
+        currentState = next;
+        events.onStateChange?.(next);
+    };
+    emitState(currentState);
+    try {
+        const assembly = await createAssembly({
+            templateId: options.templateId,
+            steps: options.steps,
+            fields: options.fields,
+            notifyUrl: options.notifyUrl,
+            numExpectedUploadFiles: options.numExpectedUploadFiles ?? 1,
+            expires: options.expires,
+            additionalParams: options.additionalParams,
+            userId: options.userId,
+        });
+        const data = assembly.data;
+        options.onAssemblyCreated?.(assembly);
+        const { endpoint, metadata } = buildTusUploadConfig(data, file, {
+            fieldName: options.fieldName,
+            metadata: options.metadata,
+        });
+        const getStatus = (error) => error.originalResponse?.getStatus &&
+            typeof error.originalResponse.getStatus === "function"
+            ? error.originalResponse.getStatus()
+            : 0;
+        const retryDelays = options.retryDelays
+            ? [...options.retryDelays]
+            : [1000, 5000, 15000, 30000];
+        const rateLimitRetryDelays = options.rateLimitRetryDelays
+            ? [...options.rateLimitRetryDelays]
+            : [20_000, 40_000, 80_000];
+        const shouldRetry = (error) => {
+            const status = getStatus(error);
+            if (!status)
+                return true;
+            if (status === 409 || status === 423)
+                return true;
+            return status < 400 || status >= 500;
         };
-        xhr.onload = () => {
+        let uploadUrl = null;
+        let rateLimitAttempt = 0;
+        const runUpload = () => new Promise((resolve, reject) => {
+            let uploader;
+            const uploadOptions = {
+                endpoint,
+                metadata,
+                retryDelays,
+                uploadDataDuringCreation: options.uploadDataDuringCreation ?? false,
+                onUploadUrlAvailable: () => {
+                    uploadUrl = uploader.url;
+                },
+                onShouldRetry: (error, retryAttempt) => options.onShouldRetry?.(error, retryAttempt) ?? shouldRetry(error),
+                onProgress: (bytesUploaded, bytesTotal) => {
+                    const progress = Math.round((bytesUploaded / bytesTotal) * 100);
+                    emitState({ isUploading: true, progress, error: null });
+                    options.onProgress?.(progress);
+                },
+                onError: (error) => {
+                    reject(error);
+                },
+                onSuccess: () => {
+                    resolve();
+                },
+            };
+            if (options.chunkSize !== undefined) {
+                uploadOptions.chunkSize = options.chunkSize;
+            }
+            if (uploadUrl) {
+                uploadOptions.uploadUrl = uploadUrl;
+            }
+            if (options.overridePatchMethod !== undefined) {
+                uploadOptions.overridePatchMethod = options.overridePatchMethod;
+            }
+            if (options.storeFingerprintForResuming !== undefined) {
+                uploadOptions.storeFingerprintForResuming =
+                    options.storeFingerprintForResuming;
+            }
+            if (options.removeFingerprintOnSuccess !== undefined) {
+                uploadOptions.removeFingerprintOnSuccess =
+                    options.removeFingerprintOnSuccess;
+            }
+            uploader = new Upload(file, uploadOptions);
+            uploader.start();
+        });
+        while (true) {
             try {
-                const response = JSON.parse(xhr.responseText);
-                if (xhr.status >= 200 && xhr.status < 300) {
-                    resolve(response);
-                }
-                else {
-                    reject(new Error(`Transloadit upload failed (${xhr.status}): ${JSON.stringify(response)}`));
-                }
+                await runUpload();
+                break;
             }
             catch (error) {
-                reject(error);
+                const status = getStatus(error);
+                if (status === 429 && rateLimitAttempt < rateLimitRetryDelays.length) {
+                    const delay = rateLimitRetryDelays[rateLimitAttempt] ?? 0;
+                    rateLimitAttempt += 1;
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                    continue;
+                }
+                throw error;
             }
-        };
-        xhr.onerror = () => {
-            reject(new Error("Transloadit upload failed"));
-        };
-        xhr.send(formData);
-    });
+        }
+        emitState({ isUploading: false, progress: 100, error: null });
+        return assembly;
+    }
+    catch (error) {
+        const err = error instanceof Error
+            ? error
+            : transloaditError("upload", "Upload failed");
+        emitState({ isUploading: false, progress: 0, error: err });
+        throw err;
+    }
 }
-export function useTransloaditUpload(generateUploadParams) {
-    const generate = useAction(generateUploadParams);
+/**
+ * @deprecated Prefer `useTransloaditUpload` (single + multi-file) for new code.
+ */
+export function useTransloaditTusUpload(createAssembly) {
+    const create = useAction(createAssembly);
     const [state, setState] = useState({
         isUploading: false,
         progress: 0,
         error: null,
     });
-    const upload = useCallback(async (file, options) => {
-        setState({ isUploading: true, progress: 0, error: null });
-        try {
-            const params = await generate({
-                templateId: options.templateId,
-                steps: options.steps,
-                fields: options.fields,
-                notifyUrl: options.notifyUrl,
-                numExpectedUploadFiles: options.numExpectedUploadFiles,
-                expires: options.expires,
-                additionalParams: options.additionalParams,
-                userId: options.userId,
-            });
-            const response = await uploadViaForm(file, params, {
-                ...options,
-                onProgress: (progress) => {
-                    setState((prev) => ({ ...prev, progress }));
-                    options.onProgress?.(progress);
-                },
-            });
-            setState({ isUploading: false, progress: 100, error: null });
-            return response;
-        }
-        catch (error) {
-            const err = error instanceof Error ? error : new Error("Upload failed");
-            setState({ isUploading: false, progress: 0, error: err });
-            throw err;
-        }
-    }, [generate]);
+    const upload = useCallback(async (file, options) => uploadWithTransloaditTus(create, file, options, {
+        onStateChange: setState,
+    }), [create]);
     const reset = useCallback(() => {
         setState({ isUploading: false, progress: 0, error: null });
     }, []);
@@ -82,81 +207,577 @@ export function useTransloaditUpload(generateUploadParams) {
         error: state.error,
     }), [state.error, state.isUploading, state.progress, upload, reset]);
 }
-export function useTransloaditTusUpload(createAssembly) {
-    const create = useAction(createAssembly);
-    const [state, setState] = useState({
-        isUploading: false,
+/**
+ * Low-level multi-file tus uploader. Prefer `useTransloaditUpload` for new code.
+ */
+export function uploadFilesWithTransloaditTus(createAssembly, files, options) {
+    const concurrency = Math.max(1, options.concurrency ?? 3);
+    const state = {
+        isUploading: true,
         progress: 0,
         error: null,
-    });
-    const upload = useCallback(async (file, options) => {
-        setState({ isUploading: true, progress: 0, error: null });
-        try {
-            const assembly = await create({
-                templateId: options.templateId,
-                steps: options.steps,
-                fields: options.fields,
-                notifyUrl: options.notifyUrl,
-                numExpectedUploadFiles: options.numExpectedUploadFiles ?? 1,
-                expires: options.expires,
-                additionalParams: options.additionalParams,
-                userId: options.userId,
+    };
+    const results = files.map((file) => ({
+        file,
+        status: "canceled",
+    }));
+    const inFlight = new Set();
+    const abortController = new AbortController();
+    let cancelled = false;
+    const emitState = (next) => {
+        state.isUploading = next.isUploading;
+        state.progress = next.progress;
+        state.error = next.error;
+        options.onStateChange?.(next);
+    };
+    const cancel = () => {
+        if (cancelled)
+            return;
+        cancelled = true;
+        abortController.abort();
+        for (const uploader of inFlight) {
+            try {
+                uploader.abort(true);
+            }
+            catch {
+                // ignore abort errors
+            }
+        }
+    };
+    if (options.signal) {
+        if (options.signal.aborted) {
+            cancel();
+        }
+        else {
+            options.signal.addEventListener("abort", cancel, { once: true });
+        }
+    }
+    const promise = (async () => {
+        if (files.length === 0) {
+            throw transloaditError("upload", "No files provided for upload");
+        }
+        emitState({ ...state });
+        const assembly = await createAssembly({
+            templateId: options.templateId,
+            steps: options.steps,
+            fields: options.fields,
+            notifyUrl: options.notifyUrl,
+            numExpectedUploadFiles: options.numExpectedUploadFiles ?? files.length,
+            expires: options.expires,
+            additionalParams: options.additionalParams,
+            userId: options.userId,
+        });
+        options.onAssemblyCreated?.(assembly);
+        const getStatus = (error) => error.originalResponse?.getStatus &&
+            typeof error.originalResponse.getStatus === "function"
+            ? error.originalResponse.getStatus()
+            : 0;
+        const retryDelays = options.retryDelays
+            ? [...options.retryDelays]
+            : [1000, 5000, 15000, 30000];
+        const rateLimitRetryDelays = options.rateLimitRetryDelays
+            ? [...options.rateLimitRetryDelays]
+            : [20_000, 40_000, 80_000];
+        const shouldRetry = (error) => {
+            const status = getStatus(error);
+            if (!status)
+                return true;
+            if (status === 409 || status === 423)
+                return true;
+            return status < 400 || status >= 500;
+        };
+        const perFileBytes = new Map();
+        files.forEach((file, index) => {
+            perFileBytes.set(index, { uploaded: 0, total: file.size });
+        });
+        const updateOverallProgress = () => {
+            let totalUploaded = 0;
+            let totalBytes = 0;
+            for (const { uploaded, total } of perFileBytes.values()) {
+                totalUploaded += uploaded;
+                totalBytes += total;
+            }
+            const overall = totalBytes > 0 ? Math.round((totalUploaded / totalBytes) * 100) : 0;
+            emitState({ isUploading: true, progress: overall, error: null });
+            options.onOverallProgress?.(overall);
+        };
+        const resolveMetadata = (file) => typeof options.metadata === "function"
+            ? options.metadata(file)
+            : options.metadata;
+        const resolveFieldName = (file) => typeof options.fieldName === "function"
+            ? options.fieldName(file)
+            : options.fieldName;
+        const uploadFile = async (file, index) => {
+            const { endpoint, metadata } = buildTusUploadConfig(assembly.data, file, {
+                fieldName: resolveFieldName(file),
+                metadata: resolveMetadata(file),
             });
-            const data = assembly.data;
-            const tusUrl = (typeof data.tus_url === "string" && data.tus_url) ||
-                (typeof data.tusUrl === "string" && data.tusUrl) ||
-                "";
-            if (!tusUrl) {
-                throw new Error("Transloadit response missing tus_url for resumable upload");
-            }
-            const metadata = {
-                filename: file.name,
-                filetype: file.type,
-                ...options.metadata,
-            };
-            await new Promise((resolve, reject) => {
-                const uploader = new Upload(file, {
-                    endpoint: tusUrl,
+            let uploadUrl = null;
+            let rateLimitAttempt = 0;
+            let uploader = null;
+            const runUpload = () => new Promise((resolve, reject) => {
+                if (cancelled) {
+                    reject(transloaditError("upload", "Upload canceled"));
+                    return;
+                }
+                const onAbort = () => {
+                    reject(transloaditError("upload", "Upload canceled"));
+                };
+                abortController.signal.addEventListener("abort", onAbort, {
+                    once: true,
+                });
+                let currentUploader;
+                const uploadOptions = {
+                    endpoint,
                     metadata,
-                    chunkSize: options.chunkSize,
-                    retryDelays: options.retryDelays ?? [0, 3000, 5000, 10000],
+                    retryDelays,
+                    uploadDataDuringCreation: options.uploadDataDuringCreation ?? false,
+                    onUploadUrlAvailable: () => {
+                        uploadUrl = currentUploader.url;
+                    },
+                    onShouldRetry: (error, retryAttempt) => options.onShouldRetry?.(error, retryAttempt) ??
+                        shouldRetry(error),
                     onProgress: (bytesUploaded, bytesTotal) => {
+                        perFileBytes.set(index, {
+                            uploaded: bytesUploaded,
+                            total: bytesTotal,
+                        });
                         const progress = Math.round((bytesUploaded / bytesTotal) * 100);
-                        setState((prev) => ({ ...prev, progress }));
-                        options.onProgress?.(progress);
+                        options.onFileProgress?.(file, progress);
+                        updateOverallProgress();
                     },
                     onError: (error) => {
+                        abortController.signal.removeEventListener("abort", onAbort);
                         reject(error);
                     },
                     onSuccess: () => {
+                        abortController.signal.removeEventListener("abort", onAbort);
                         resolve();
                     },
-                });
-                uploader.start();
+                };
+                if (options.chunkSize !== undefined) {
+                    uploadOptions.chunkSize = options.chunkSize;
+                }
+                if (uploadUrl) {
+                    uploadOptions.uploadUrl = uploadUrl;
+                }
+                if (options.overridePatchMethod !== undefined) {
+                    uploadOptions.overridePatchMethod = options.overridePatchMethod;
+                }
+                if (options.storeFingerprintForResuming !== undefined) {
+                    uploadOptions.storeFingerprintForResuming =
+                        options.storeFingerprintForResuming;
+                }
+                if (options.removeFingerprintOnSuccess !== undefined) {
+                    uploadOptions.removeFingerprintOnSuccess =
+                        options.removeFingerprintOnSuccess;
+                }
+                currentUploader = new Upload(file, uploadOptions);
+                uploader = currentUploader;
+                inFlight.add(currentUploader);
+                currentUploader.start();
+            }).finally(() => {
+                if (uploader) {
+                    inFlight.delete(uploader);
+                }
             });
-            setState({ isUploading: false, progress: 100, error: null });
-            return assembly;
+            while (true) {
+                try {
+                    await runUpload();
+                    break;
+                }
+                catch (error) {
+                    if (cancelled) {
+                        throw error;
+                    }
+                    const status = getStatus(error);
+                    if (status === 429 &&
+                        rateLimitAttempt < rateLimitRetryDelays.length) {
+                        const delay = rateLimitRetryDelays[rateLimitAttempt] ?? 0;
+                        rateLimitAttempt += 1;
+                        await new Promise((resolve) => setTimeout(resolve, delay));
+                        continue;
+                    }
+                    throw error;
+                }
+            }
+        };
+        let nextIndex = 0;
+        const errors = [];
+        const worker = async () => {
+            while (true) {
+                if (cancelled)
+                    return;
+                const index = nextIndex;
+                nextIndex += 1;
+                if (index >= files.length)
+                    return;
+                const file = files[index];
+                try {
+                    await uploadFile(file, index);
+                    results[index] = { file, status: "success" };
+                    options.onFileComplete?.(file);
+                }
+                catch (error) {
+                    if (cancelled) {
+                        results[index] = { file, status: "canceled" };
+                        return;
+                    }
+                    const err = error instanceof Error
+                        ? error
+                        : transloaditError("upload", "Upload failed");
+                    results[index] = { file, status: "error", error: err };
+                    errors.push(err);
+                    options.onFileError?.(file, err);
+                    if (options.failFast ?? false) {
+                        cancel();
+                        return;
+                    }
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(concurrency, files.length) }, worker));
+        if (cancelled) {
+            const error = transloaditError("upload", "Upload canceled");
+            error.results = {
+                assemblyId: assembly.assemblyId,
+                data: assembly.data,
+                files: results,
+            };
+            throw error;
+        }
+        const hasErrors = results.some((result) => result.status === "error");
+        const resultPayload = {
+            assemblyId: assembly.assemblyId,
+            data: assembly.data,
+            files: results,
+        };
+        if (hasErrors) {
+            const error = transloaditError("upload", `Failed to upload ${errors.length} file${errors.length === 1 ? "" : "s"}`);
+            error.results =
+                resultPayload;
+            throw error;
+        }
+        emitState({ isUploading: false, progress: 100, error: null });
+        return resultPayload;
+    })();
+    return { promise, cancel };
+}
+export function useTransloaditUpload(options) {
+    const create = useAction(options.createAssembly);
+    const refresh = useAction(options.refreshAssembly);
+    const [state, setState] = useState({
+        isUploading: false,
+        progress: 0,
+        error: null,
+    });
+    const [assemblyId, setAssemblyId] = useState(null);
+    const [assemblyData, setAssemblyData] = useState(null);
+    const cancelRef = useRef(null);
+    const upload = useCallback(async (files, uploadOptions) => {
+        const resolved = files instanceof FileList
+            ? Array.from(files)
+            : Array.isArray(files)
+                ? files
+                : [files];
+        const controller = uploadFilesWithTransloaditTus(create, resolved, {
+            ...uploadOptions,
+            onStateChange: setState,
+            onAssemblyCreated: (assembly) => {
+                setAssemblyId(assembly.assemblyId);
+                setAssemblyData(assembly.data);
+                uploadOptions.onAssemblyCreated?.(assembly);
+            },
+        });
+        cancelRef.current = controller.cancel;
+        try {
+            const result = await controller.promise;
+            setAssemblyId(result.assemblyId);
+            setAssemblyData(result.data);
+            return result;
         }
         catch (error) {
-            const err = error instanceof Error ? error : new Error("Upload failed");
-            setState({ isUploading: false, progress: 0, error: err });
-            throw err;
+            const resolvedError = error instanceof Error
+                ? error
+                : transloaditError("upload", "Upload failed");
+            setState({ isUploading: false, progress: 0, error: resolvedError });
+            throw error;
+        }
+        finally {
+            cancelRef.current = null;
         }
     }, [create]);
+    const cancel = useCallback(() => {
+        cancelRef.current?.();
+    }, []);
     const reset = useCallback(() => {
+        cancelRef.current?.();
+        cancelRef.current = null;
+        setAssemblyId(null);
+        setAssemblyData(null);
         setState({ isUploading: false, progress: 0, error: null });
     }, []);
-    return useMemo(() => ({
+    const assembly = useQuery(options.getStatus, assemblyId ? { assemblyId } : "skip");
+    const parsedStatus = useMemo(() => {
+        const candidate = assembly && typeof assembly === "object"
+            ? (assembly.raw ?? assembly)
+            : assembly;
+        return parseAssemblyStatus(candidate);
+    }, [assembly]);
+    const results = useQuery(options.listResults, assemblyId ? { assemblyId } : "skip");
+    useAssemblyPoller({
+        assemblyId,
+        status: parsedStatus,
+        refresh: async () => {
+            if (!assemblyId)
+                return;
+            await refresh({ assemblyId });
+        },
+        intervalMs: options.pollIntervalMs ?? 5000,
+        shouldContinue: options.shouldContinue,
+        onError: options.onError,
+    });
+    return {
         upload,
+        cancel,
         reset,
         isUploading: state.isUploading,
         progress: state.progress,
         error: state.error,
-    }), [state.error, state.isUploading, state.progress, upload, reset]);
+        assemblyId,
+        assemblyData,
+        assembly,
+        status: parsedStatus,
+        results,
+    };
+}
+export function useTransloaditUppy(options) {
+    const create = useAction(options.createAssembly);
+    const refresh = useAction(options.refreshAssembly);
+    const [isUploading, setIsUploading] = useState(false);
+    const [error, setError] = useState(null);
+    const [assemblyId, setAssemblyId] = useState(null);
+    const [assemblyData, setAssemblyData] = useState(null);
+    const [uploadResult, setUploadResult] = useState(null);
+    const assembly = useQuery(options.getStatus, assemblyId ? { assemblyId } : "skip");
+    const results = useQuery(options.listResults, assemblyId ? { assemblyId } : "skip");
+    const parsedStatus = useMemo(() => {
+        const candidate = assembly && typeof assembly === "object"
+            ? (assembly.raw ?? assembly)
+            : assembly;
+        return parseAssemblyStatus(candidate);
+    }, [assembly]);
+    useAssemblyPoller({
+        assemblyId,
+        status: parsedStatus,
+        refresh: async () => {
+            if (!assemblyId)
+                return;
+            await refresh({ assemblyId });
+        },
+        intervalMs: options.pollIntervalMs ?? 5000,
+        shouldContinue: options.shouldContinue,
+        onError: options.onError,
+    });
+    const startUpload = useCallback(async (overrides) => {
+        setError(null);
+        setIsUploading(true);
+        try {
+            const files = options.uppy.getFiles();
+            if (files.length === 0) {
+                throw transloaditError("upload", "No files provided for upload");
+            }
+            const createAssemblyArgs = {
+                ...(options.createAssemblyArgs ?? {}),
+                ...(overrides?.createAssemblyArgs ?? {}),
+            };
+            const { assembly, uploadResult: result } = await uploadWithAssembly(create, options.uppy, {
+                fileCount: overrides?.fileCount ?? options.fileCount ?? files.length,
+                fieldName: overrides?.fieldName ?? options.fieldName,
+                metadata: overrides?.metadata ?? options.metadata,
+                addRequestId: overrides?.addRequestId ?? options.addRequestId,
+                createAssemblyArgs,
+                onAssemblyCreated: (created) => {
+                    const typed = created;
+                    setAssemblyId(typed.assemblyId);
+                    setAssemblyData(typed.data);
+                    options.onAssemblyCreated?.(typed);
+                    overrides?.onAssemblyCreated?.(created);
+                },
+            });
+            setAssemblyId(assembly.assemblyId);
+            setAssemblyData(assembly.data);
+            setUploadResult(result);
+            options.onUploadResult?.(result);
+            setIsUploading(false);
+            return { assembly, uploadResult: result };
+        }
+        catch (err) {
+            const resolved = err instanceof Error
+                ? err
+                : transloaditError("upload", "Upload failed");
+            setError(resolved);
+            setIsUploading(false);
+            throw resolved;
+        }
+    }, [
+        create,
+        options.addRequestId,
+        options.createAssemblyArgs,
+        options.fieldName,
+        options.fileCount,
+        options.metadata,
+        options.onAssemblyCreated,
+        options.onUploadResult,
+        options.uppy,
+    ]);
+    const reset = useCallback(() => {
+        setIsUploading(false);
+        setError(null);
+        setAssemblyId(null);
+        setAssemblyData(null);
+        setUploadResult(null);
+    }, []);
+    const stage = useMemo(() => {
+        if (error)
+            return "error";
+        if (isUploading)
+            return "uploading";
+        return parsedStatus ? getAssemblyStage(parsedStatus) : null;
+    }, [error, isUploading, parsedStatus]);
+    return {
+        startUpload,
+        reset,
+        isUploading,
+        error,
+        assemblyId,
+        assemblyData,
+        assembly,
+        status: parsedStatus,
+        results,
+        stage,
+        uploadResult,
+    };
 }
 export function useAssemblyStatus(getStatus, assemblyId) {
     return useQuery(getStatus, { assemblyId });
 }
+export function useAssemblyStatusWithPolling(getStatus, refreshAssembly, assemblyId, options) {
+    const status = useQuery(getStatus, { assemblyId });
+    const refresh = useAction(refreshAssembly);
+    const statusRef = useRef(status);
+    const shouldContinueRef = useRef(options?.shouldContinue);
+    const onErrorRef = useRef(options?.onError);
+    useEffect(() => {
+        statusRef.current = status;
+    }, [status]);
+    useEffect(() => {
+        shouldContinueRef.current = options?.shouldContinue;
+    }, [options?.shouldContinue]);
+    useEffect(() => {
+        onErrorRef.current = options?.onError;
+    }, [options?.onError]);
+    useEffect(() => {
+        if (!assemblyId)
+            return;
+        const intervalMs = options?.pollIntervalMs ?? 5000;
+        if (intervalMs <= 0)
+            return;
+        const shouldKeepPolling = () => {
+            const shouldContinue = shouldContinueRef.current?.();
+            if (shouldContinue === false)
+                return false;
+            if (!options?.stopOnTerminal)
+                return true;
+            const current = statusRef.current;
+            const rawCandidate = current && typeof current === "object"
+                ? (current.raw ?? current)
+                : current;
+            const parsed = parseAssemblyStatus(rawCandidate);
+            return !(parsed ? isAssemblyTerminal(parsed) : false);
+        };
+        if (!shouldKeepPolling())
+            return;
+        let cancelled = false;
+        let intervalId = null;
+        let inFlight = false;
+        const tick = async () => {
+            if (cancelled)
+                return;
+            if (!shouldKeepPolling()) {
+                if (intervalId)
+                    clearInterval(intervalId);
+                cancelled = true;
+                return;
+            }
+            if (inFlight)
+                return;
+            inFlight = true;
+            try {
+                await refresh({ assemblyId });
+            }
+            catch (error) {
+                const resolved = error instanceof Error
+                    ? error
+                    : transloaditError("polling", "Refresh failed");
+                onErrorRef.current?.(resolved);
+            }
+            finally {
+                inFlight = false;
+            }
+        };
+        intervalId = setInterval(() => {
+            void tick();
+        }, intervalMs);
+        void tick();
+        return () => {
+            cancelled = true;
+            if (intervalId)
+                clearInterval(intervalId);
+        };
+    }, [assemblyId, options?.pollIntervalMs, options?.stopOnTerminal, refresh]);
+    return status;
+}
+/**
+ * @deprecated Prefer `useAssemblyStatusWithPolling` for public usage.
+ */
+export function useAssemblyPoller(options) {
+    const refreshRef = useRef(options.refresh);
+    const onErrorRef = useRef(options.onError);
+    const shouldContinueRef = useRef(options.shouldContinue);
+    const statusRef = useRef(options.status);
+    useEffect(() => {
+        refreshRef.current = options.refresh;
+    }, [options.refresh]);
+    useEffect(() => {
+        onErrorRef.current = options.onError;
+    }, [options.onError]);
+    useEffect(() => {
+        shouldContinueRef.current = options.shouldContinue;
+    }, [options.shouldContinue]);
+    useEffect(() => {
+        statusRef.current = options.status;
+    }, [options.status]);
+    useEffect(() => {
+        if (!options.assemblyId)
+            return;
+        const controller = pollAssembly({
+            intervalMs: options.intervalMs,
+            refresh: () => refreshRef.current(),
+            shouldContinue: () => shouldContinueRef.current?.() ?? false,
+            isTerminal: () => {
+                const current = statusRef.current;
+                return current ? isAssemblyTerminal(current) : false;
+            },
+            onError: (error) => {
+                onErrorRef.current?.(error);
+            },
+        });
+        return () => {
+            controller.stop();
+        };
+    }, [options.assemblyId, options.intervalMs]);
+}
 export function useTransloaditFiles(listResults, args) {
     return useQuery(listResults, args);
 }