@better-s3/react 3.1045.1 → 3.1046.0

package/dist/index.js

@@ -1,2 +1,1418 @@
-import {validateFile}from'@better-s3/server';export{createS3Api as createPresignApi,createS3Api,validateFile}from'@better-s3/server';import {useState,useRef,useCallback}from'react';function K(e,a){if(!e)return a;let o=e.match(/filename\*=UTF-8''([^;,\s]+)/i);if(o)try{return decodeURIComponent(o[1])}catch{}let d=e.match(/filename="([^"]+)"/i);return d?d[1]:a}function ee(e){if(e===0)return "0 B";let a=["B","KB","MB","GB","TB"],o=Math.floor(Math.log(e)/Math.log(1024));return `${(e/Math.pow(1024,o)).toFixed(o===0?0:1)} ${a[o]}`}async function R(e,a,o){let d;for(let s=0;s<=a;s++)try{return await e()}catch(g){if(g.name==="AbortError")throw g;if(d=g,s<a){let c=1e3*2**s;if(await new Promise(t=>setTimeout(t,c)),o?.aborted)throw new DOMException("Upload aborted","AbortError")}}throw d}function B(e,a,o,d,s){return new Promise((g,c)=>{let t=new XMLHttpRequest,n=()=>{t.abort(),c(new DOMException("Upload aborted","AbortError"));};s?.addEventListener("abort",n,{once:true}),t.upload.addEventListener("progress",i=>{i.lengthComputable&&d?.({loaded:i.loaded,total:i.total,percent:Math.round(i.loaded/i.total*100)});}),t.addEventListener("load",()=>{s?.removeEventListener("abort",n),t.status>=200&&t.status<300?(d?.({loaded:e.size,total:e.size,percent:100}),g()):c(new Error(`Upload failed: ${t.status} ${t.statusText}`));}),t.addEventListener("error",()=>{s?.removeEventListener("abort",n),c(new Error("Upload failed: network error"));}),t.addEventListener("abort",()=>{s?.removeEventListener("abort",n),c(new DOMException("Upload aborted","AbortError"));});let p=new FormData;for(let[i,r]of Object.entries(o))p.append(i,r);p.append("file",e),t.open("POST",a),t.send(p);})}function q(e,a,o,d,s){return new Promise((g,c)=>{let t=new XMLHttpRequest,n=()=>{t.abort(),c(new DOMException("Upload aborted","AbortError"));};s?.addEventListener("abort",n,{once:true}),t.upload.addEventListener("progress",p=>{p.lengthComputable&&d?.({loaded:p.loaded,total:p.total,percent:Math.round(p.loaded/p.total*100)});}),t.addEventListener("load",()=>{s?.removeEventListener("abort",n),t.status>=200&&t.status<300?(d?.({loaded:e.size,total:e.size,percent:100}),g()):c(new Error(`Upload failed: ${t.status} ${t.statusText}`));}),t.addEventListener("error",()=>{s?.removeEventListener("abort",n),c(new Error("Upload failed: network error"));}),t.addEventListener("abort",()=>{s?.removeEventListener("abort",n),c(new DOMException("Upload aborted","AbortError"));}),t.open("PUT",a);for(let[p,i]of Object.entries(o))t.setRequestHeader(p,i);t.send(e);})}function G(e,a,o,d,s,g){return new Promise((c,t)=>{let n=new XMLHttpRequest,p=()=>{n.abort(),t(new DOMException("Upload aborted","AbortError"));};g?.addEventListener("abort",p,{once:true}),n.upload.addEventListener("progress",i=>{i.lengthComputable&&(o.bytes=i.loaded,s());}),n.addEventListener("load",()=>{g?.removeEventListener("abort",p),n.status>=200&&n.status<300?(o.bytes=e.size,s(),c()):t(new Error(`Part upload failed: ${n.status}`));}),n.addEventListener("error",()=>{g?.removeEventListener("abort",p),t(new Error("Part upload failed: network error"));}),n.addEventListener("abort",()=>{g?.removeEventListener("abort",p),t(new DOMException("Upload aborted","AbortError"));}),n.open("PUT",a),n.send(e);})}async function X(e,a,o,d,s,g,c,t){let n=t?.contentType??a.type,{uploadId:p,key:i}=await e.multipart.init({key:o,contentType:n,fileSize:a.size,fileName:t?.fileName!==null?t?.fileName??a.name:void 0,metadata:t?.metadata,bucket:t?.bucket,acl:t?.acl}),r=Math.ceil(a.size/d),U=[],l=Array.from({length:r},()=>({bytes:0})),u=()=>{let f=l.reduce((m,h)=>m+h.bytes,0);g?.({loaded:f,total:a.size,percent:Math.round(f/a.size*100)});};try{for(let m=0;m<r;m+=s){if(c?.aborted)throw new DOMException("Upload aborted","AbortError");let h=Math.min(m+s,r),P=[];for(let w=m;w<h;w++){let S=w*d,F=Math.min(S+d,a.size),y=a.slice(S,F),v=w+1;P.push(R(async()=>{let{presignedUrl:O}=await e.multipart.signPart({key:i,uploadId:p,partNumber:v,partSize:y.size,bucket:t?.bucket});return l[w].bytes=0,await G(y,O,l[w],a.size,u,c),{partNumber:v}},3,c));}let b=await Promise.all(P);U.push(...b);}U.sort((m,h)=>m.partNumber-h.partNumber);let f=await e.multipart.complete({key:i,uploadId:p,parts:U,bucket:t?.bucket});return g?.({loaded:a.size,total:a.size,percent:100}),f.eTag}catch(f){throw e.multipart.abort({key:i,uploadId:p,bucket:t?.bucket}).catch(()=>{}),f}}async function E(e,a,o,d={},s={},g,c){let t=d.multipartThreshold??31457280,n=d.multipart===true&&a.size>=t,p=d.concurrentParts??3,i=c?.contentType??a.type,r;return n?(s.onPhaseChange?.("uploading"),r=await X(e,a,o,10485760,p,s.onProgress,g,c)):(await R(async()=>{s.onPhaseChange?.("presigning");let l=await e.upload({key:o,contentType:i,fileSize:a.size,fileName:c?.fileName!==null?c?.fileName??a.name:void 0,metadata:c?.metadata,bucket:c?.bucket,acl:c?.acl});s.onPhaseChange?.("uploading"),l.method==="put"?await q(a,l.url,l.headers??{},s.onProgress,g):await B(a,l.url,l.fields??{},s.onProgress,g);},3,g),s.onPhaseChange?.("finalizing"),r=(await e.confirm({key:o,bucket:c?.bucket})).eTag),{key:o,eTag:r}}async function x(e,a,o={},d={},s,g){let c=a.map(U=>({...U,status:"pending",progress:{loaded:0,total:U.file.size,percent:0},result:null,error:null})),t=()=>{let U=c.reduce((u,f)=>u+f.progress.loaded,0),l=c.reduce((u,f)=>u+f.progress.total,0);d.onTotalProgress?.({loaded:U,total:l,percent:l>0?Math.round(U/l*100):0});},n=0,p=async()=>{for(;n<c.length;){if(s?.aborted)return;let U=n++,l=c[U];l.status="uploading";try{let u=await E(e,l.file,l.objectKey,o,{onProgress:f=>{l.progress=f,d.onFileProgress?.(l.id,f),t();}},s,g?.(l.file));l.status="success",l.result=u,l.progress={loaded:l.file.size,total:l.file.size,percent:100},d.onFileSuccess?.(l.id,u),t();}catch(u){if(u.name==="AbortError"){l.status="error",l.error="Upload cancelled";return}let f=u instanceof Error?u.message:"Upload failed";l.status="error",l.error=f,d.onFileError?.(l.id,f),t();}}},i=o.concurrentFiles??2,r=Array.from({length:Math.min(i,a.length)},()=>p());return await Promise.all(r),c}var se={loaded:0,total:0,percent:0},D={phase:"idle",progress:se,error:null,result:null,fileName:null,fileSize:null};function C(e){let[a,o]=useState(D),d=useRef(e);d.current=e;let s=useRef(null),g=useCallback(async(n,p,i)=>{o({...D,phase:"validating",fileName:n.name,fileSize:n.size});let r=d.current,U=validateFile(n,{accept:r.accept,maxFileSize:r.maxFileSize});if(U){o(u=>({...u,phase:"error",error:U})),r.onError?.(n,new Error(U),"validating");return}if(r.beforeUpload&&!await r.beforeUpload(n)){o(f=>({...f,phase:"error",error:"Upload blocked by beforeUpload hook"})),r.onError?.(n,new Error("blocked"),"validating");return}o(u=>({...u,phase:"presigning"})),r.onUploadStart?.(n,p);let l=new AbortController;s.current=l;try{let u=await E(r.api,n,p,{multipart:r.multipart,multipartThreshold:r.multipartThreshold,concurrentParts:r.concurrentParts},{onProgress:f=>{o(m=>({...m,progress:f})),r.onProgress?.(n,f);},onPhaseChange:f=>o(m=>({...m,phase:f}))},l.signal,i);o(f=>({...f,phase:"success",result:u,progress:{loaded:n.size,total:n.size,percent:100}})),await r.onSuccess?.(n,u);}catch(u){if(u.name==="AbortError"){r.onCancel?.(n),o(D);return}let f=u instanceof Error?u.message:"Upload failed";o(m=>({...m,phase:"error",error:f})),r.onError?.(n,u,"uploading");}finally{s.current=null;}},[]),c=useCallback(()=>{s.current?.abort(),o(D);},[]),t=useCallback(()=>{s.current?.abort(),o(D);},[]);return {...a,upload:g,cancel:c,reset:t}}var ae={loaded:0,total:0,percent:0},A={phase:"idle",files:[],totalProgress:ae,error:null},ie=0;function pe(){return `file-${++ie}`}function L(e){let[a,o]=useState(A),d=useRef(e);d.current=e;let s=useRef(null),g=useRef(new Map),c=useCallback(async(p,i)=>{let r=d.current,U=[],l=[],u=new Map;if(o(m=>({...m,phase:"validating",error:null})),r.maxFiles&&p.length>r.maxFiles){let m=`Too many files. Maximum is ${r.maxFiles}.`;o(h=>({...h,phase:"error",error:m})),r.onError?.(new Error(m));return}for(let m of p){let h=validateFile(m,{accept:r.accept,maxFileSize:r.maxFileSize});if(h){let P=`${m.name}: ${h}`;o(b=>({...b,phase:"error",error:P})),r.onError?.(new Error(P));return}}if(r.beforeUpload&&!await r.beforeUpload(p)){o(h=>({...h,phase:"error",error:"Upload blocked by beforeUpload hook"})),r.onError?.(new Error("blocked"));return}for(let m of p){let h=pe(),P=i(m);U.push({id:h,file:m,objectKey:P}),u.set(h,m),l.push({id:h,fileName:m.name,fileSize:m.size,status:"pending",progress:{loaded:0,total:m.size,percent:0},error:null});}g.current=u,o({phase:"uploading",files:l,totalProgress:{loaded:0,total:p.reduce((m,h)=>m+h.size,0),percent:0},error:null}),r.onUploadStart?.(p);let f=new AbortController;s.current=f;try{let m=await x(r.api,U,{multipart:r.multipart,multipartThreshold:r.multipartThreshold,concurrentParts:r.concurrentParts,concurrentFiles:r.concurrentFiles},{onFileProgress:(b,w)=>{o(F=>({...F,files:F.files.map(y=>y.id===b?{...y,status:"uploading",progress:w}:y)}));let S=u.get(b);S&&r.onFileProgress?.(S,w);},onFileSuccess:(b,w)=>{o(F=>({...F,files:F.files.map(y=>y.id===b?{...y,status:"success",progress:{loaded:y.fileSize,total:y.fileSize,percent:100}}:y)}));let S=u.get(b);S&&r.onFileSuccess?.(S,w);},onFileError:(b,w)=>{o(F=>({...F,files:F.files.map(y=>y.id===b?{...y,status:"error",error:w}:y)}));let S=u.get(b);S&&r.onFileError?.(S,w);},onTotalProgress:b=>{o(w=>({...w,totalProgress:b})),r.onProgress?.(b);}},f.signal,b=>{let w=r.getUploadOptions?.(b);return r.uploadOptions?{...r.uploadOptions,...w}:w??{}}),h=m.some(b=>b.status==="error"),P=m.filter(b=>b.result!==null).map(b=>b.result);o(b=>({...b,phase:h?"error":"success",error:h?`${m.filter(w=>w.status==="error").length} file(s) failed`:null,totalProgress:h?b.totalProgress:{loaded:b.totalProgress.total,total:b.totalProgress.total,percent:100}})),h||await r.onSuccess?.(P);}catch(m){if(m.name==="AbortError"){r.onCancel?.(),o(A);return}let h=m instanceof Error?m.message:"Upload failed";o(P=>({...P,phase:"error",error:h})),r.onError?.(m);}finally{s.current=null;}},[]),t=useCallback(()=>{s.current?.abort(),o(A);},[]),n=useCallback(()=>{s.current?.abort(),o(A);},[]);return {...a,upload:c,cancel:t,reset:n}}var Y={loaded:0,total:0,percent:0};function ce(e){let a=(e.maxFiles??1)>1,o={api:e.api,accept:e.accept,maxFileSize:e.maxFileSize,multipart:e.multipart,multipartThreshold:e.multipartThreshold,concurrentParts:e.concurrentParts,beforeUpload:e.beforeUpload,onUploadStart:e.onUploadStart,onProgress:e.onProgress,onSuccess:e.onSuccess,onError:e.onError,onCancel:e.onCancel},d={api:e.api,accept:e.accept,maxFileSize:e.maxFileSize,maxFiles:e.maxFiles,multipart:e.multipart,multipartThreshold:e.multipartThreshold,concurrentParts:e.concurrentParts,concurrentFiles:e.concurrentFiles,uploadOptions:e.uploadOptions,getUploadOptions:e.getUploadOptions,beforeUpload:e.beforeUpload,onUploadStart:e.onUploadStart,onProgress:e.onProgress,onSuccess:e.onSuccess,onError:e.onError,onCancel:e.onCancel,onFileProgress:e.onFileProgress,onFileSuccess:e.onFileSuccess,onFileError:e.onFileError},s=C(o),g=L(d),c=useRef(null),[t,n]=useState(null),p=l=>typeof e.objectKey=="function"?e.objectKey(l):e.objectKey,i=async l=>{if(a){if(!l?.length)return;await g.upload(Array.from(l),p);}else {let u=l?.[0];if(!u)return;n({name:u.name,size:u.size}),await s.upload(u,p(u),{...e.uploadOptions,...e.getUploadOptions?.(u)});}},r=()=>c.current?.click(),U=a?g.phase==="uploading":s.phase==="uploading";return {mode:a?"multi":"single",phase:a?g.phase:s.phase,fileInfo:a?null:t,progress:a?Y:s.progress,files:a?g.files:[],totalProgress:a?g.totalProgress:Y,error:a?g.error:s.error,isUploading:U,handleFiles:i,openFilePicker:r,cancel:a?g.cancel:s.cancel,reset:a?g.reset:()=>{s.reset(),n(null);},inputProps:{ref:c,type:"file",...a&&{multiple:true},accept:e.accept?.join(","),hidden:true,onChange:l=>{i(l.target.files),l.target.value="";}},dropHandlers:{onDragOver:l=>{l.preventDefault(),l.stopPropagation();},onDrop:l=>{l.preventDefault(),l.stopPropagation(),U||i(l.dataTransfer.files);}}}}var Z={phase:"idle",error:null,url:null,expiresIn:null};function fe(e){let[a,o]=useState(Z),d=useRef(e);d.current=e;let s=useCallback(async(t,n)=>{let p=d.current;o({phase:"presigning",error:null,url:null,expiresIn:null});try{let i=await p.api.download(t,{fileName:n,bucket:p.bucket});return o({phase:"idle",error:null,url:i.url,expiresIn:i.expiresIn}),{url:i.url,expiresIn:i.expiresIn}}catch(i){let r=i instanceof Error?i.message:"Download failed";return o({phase:"error",error:r,url:null,expiresIn:null}),p.onError?.(t,i),null}},[]),g=useCallback(async(t,n)=>{let p=d.current;if(p.beforeDownload&&!await p.beforeDownload(t)){o({phase:"error",error:"Download blocked by beforeDownload hook",url:null,expiresIn:null}),p.onError?.(t,new Error("blocked"));return}let i=await s(t,n);i&&(window.location.href=i.url,p.onInitiated?.(t));},[s]),c=useCallback(()=>{o(Z);},[]);return {...a,download:g,presign:s,reset:c}}var Q={loaded:0,total:0,percent:0},M={phase:"idle",progress:Q,error:null,fileName:null,fileSize:null};function be(e){let[a,o]=useState(M),d=useRef(e);d.current=e;let s=useRef(null),g=useCallback(async(n,p)=>{let i=n.split("/").pop()??n,r=d.current;if(r.beforeDownload&&!await r.beforeDownload(n)){o(l=>({...l,phase:"error",error:"Download blocked by beforeDownload hook"})),r.onError?.(n,new Error("blocked"),"presigning");return}o({phase:"presigning",progress:Q,error:null,fileName:p??null,fileSize:null});try{let{url:U}=await r.api.download(n,{fileName:p,bucket:r.bucket});o(y=>({...y,phase:"downloading"})),r.onDownloadStart?.(n);let l=new AbortController;s.current=l;let u=await fetch(U,{signal:l.signal});if(!u.ok)throw new Error(u.status===404?"File not found":`Download failed (${u.status})`);let f=Number(u.headers.get("content-length")||0),m=p??K(u.headers.get("content-disposition"),i);o(y=>({...y,fileName:m,fileSize:f||null}));let h=u.body?.getReader();if(!h)throw new Error("ReadableStream not supported");let P=[],b=0;for(;;){let{done:y,value:v}=await h.read();if(y)break;P.push(v),b+=v.byteLength;let O=f>0?Math.round(b/f*100):0,$={loaded:b,total:f,percent:O};o(W=>({...W,progress:$})),r.onProgress?.(n,$);}let w=new Blob(P),S=URL.createObjectURL(w),F=document.createElement("a");F.href=S,F.download=m??i,F.click(),URL.revokeObjectURL(S),o(y=>({...y,phase:"success",fileSize:w.size,progress:{loaded:w.size,total:w.size,percent:100}})),await r.onSuccess?.(n,m??i);}catch(U){if(U.name==="AbortError"){r.onCancel?.(n),o(M);return}let l=U instanceof Error?U.message:"Download failed";o(u=>({...u,phase:"error",error:l})),r.onError?.(n,U,"downloading");}finally{s.current=null;}},[]),c=useCallback(()=>{s.current?.abort(),o(M);},[]),t=useCallback(()=>{s.current?.abort(),o(M);},[]);return {...a,download:g,cancel:c,reset:t}}var _={phase:"idle",error:null};function we(e){let[a,o]=useState(_),[d,s]=useState(null),g=useRef(e);g.current=e;let c=useCallback(i=>{s(i),o({phase:"confirming",error:null});},[]),t=useCallback(async()=>{if(!d)return;let i=g.current;if(i.beforeDelete&&!await i.beforeDelete(d)){o({phase:"error",error:"Delete blocked by beforeDelete hook"}),i.onError?.(d,new Error("blocked"),"confirming"),s(null);return}o({phase:"deleting",error:null}),i.onDeleteStart?.(d);try{await i.api.delete(d,{bucket:i.bucket}),o({phase:"success",error:null}),await i.onSuccess?.(d),s(null);}catch(r){let U=r instanceof Error?r.message:"Delete failed";o({phase:"error",error:U}),i.onError?.(d,r,"deleting");}},[d]),n=useCallback(()=>{s(null),o(_);},[]),p=useCallback(()=>{s(null),o(_);},[]);return {...a,pendingKey:d,requestDelete:c,confirmDelete:t,cancelDelete:n,reset:p}}export{ee as formatFileSize,E as uploadFile,x as uploadFiles,we as useDelete,fe as useDownload,be as useFetchDownload,L as useMultiUpload,C as useUpload,ce as useUploadControls};//# sourceMappingURL=index.js.map
+import { createContext, useContext, useState, useRef, useCallback } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+// src/types/error.ts
+var S3UploadError = class extends Error {
+  constructor(message, code, statusCode, phase) {
+    super(message);
+    this.name = "S3UploadError";
+    this.code = code;
+    this.statusCode = statusCode;
+    this.phase = phase;
+  }
+};
+
+// src/api.ts
+function createS3Client(input) {
+  return input;
+}
+var createS3Api = createS3Client;
+var S3Context = createContext(null);
+function S3Provider({
+  client,
+  children
+}) {
+  return /* @__PURE__ */ jsx(S3Context.Provider, { value: client, children });
+}
+function useS3Client() {
+  const ctx = useContext(S3Context);
+  if (!ctx) {
+    throw new Error(
+      "[better-s3] No S3Api client found. Either wrap your app with <S3Provider client={...}> or pass `api` directly to the hook."
+    );
+  }
+  return ctx;
+}
+
+// src/store/local-storage-store.ts
+var STORAGE_PREFIX = "better-s3:upload:";
+function createLocalStorageStore() {
+  return {
+    get(key, fileSize) {
+      try {
+        const raw = localStorage.getItem(STORAGE_PREFIX + key);
+        if (!raw) return null;
+        const stored = JSON.parse(raw);
+        return stored.fileSize === fileSize ? stored : null;
+      } catch {
+        return null;
+      }
+    },
+    set(upload) {
+      try {
+        localStorage.setItem(
+          STORAGE_PREFIX + upload.key,
+          JSON.stringify(upload)
+        );
+      } catch {
+      }
+    },
+    delete(key) {
+      try {
+        localStorage.removeItem(STORAGE_PREFIX + key);
+      } catch {
+      }
+    }
+  };
+}
+
+// src/store/memory-store.ts
+function createMemoryStore() {
+  const map = /* @__PURE__ */ new Map();
+  return {
+    get(key, fileSize) {
+      const stored = map.get(key);
+      if (!stored) return null;
+      return stored.fileSize === fileSize ? stored : null;
+    },
+    set(upload) {
+      map.set(upload.key, upload);
+    },
+    delete(key) {
+      map.delete(key);
+    }
+  };
+}
+
+// src/upload/constants.ts
+var DEFAULT_MULTIPART_THRESHOLD = 50 * 1024 * 1024;
+var DEFAULT_PART_SIZE = 5 * 1024 * 1024;
+var MAX_RETRIES = 3;
+var RETRY_BASE_DELAY = 1e3;
+var DEFAULT_CONCURRENT_PARTS = 2;
+var DEFAULT_CONCURRENT_FILES = 2;
+
+// src/upload/retry.ts
+async function withRetry(fn, retryConfig, signal) {
+  const maxRetries = retryConfig?.maxRetries ?? MAX_RETRIES;
+  const baseDelay = retryConfig?.baseDelay ?? RETRY_BASE_DELAY;
+  let lastError;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (err.name === "AbortError") throw err;
+      lastError = err;
+      if (attempt < maxRetries) {
+        const delay = baseDelay * 2 ** attempt;
+        await new Promise((r) => setTimeout(r, delay));
+        if (signal?.aborted)
+          throw new DOMException("Upload aborted", "AbortError");
+      }
+    }
+  }
+  throw lastError;
+}
+
+// src/upload/simple.ts
+function uploadSimple(file, url, fields, onProgress, signal) {
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    const onAbort = () => {
+      xhr.abort();
+      reject(new DOMException("Upload aborted", "AbortError"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    xhr.upload.addEventListener("progress", (e) => {
+      if (e.lengthComputable) {
+        onProgress?.({
+          loaded: e.loaded,
+          total: e.total,
+          percent: Math.round(e.loaded / e.total * 100)
+        });
+      }
+    });
+    xhr.addEventListener("load", () => {
+      signal?.removeEventListener("abort", onAbort);
+      if (xhr.status >= 200 && xhr.status < 300) {
+        onProgress?.({ loaded: file.size, total: file.size, percent: 100 });
+        resolve();
+      } else {
+        reject(new Error(`Upload failed: ${xhr.status} ${xhr.statusText}`));
+      }
+    });
+    xhr.addEventListener("error", () => {
+      signal?.removeEventListener("abort", onAbort);
+      reject(new Error("Upload failed: network error"));
+    });
+    xhr.addEventListener("abort", () => {
+      signal?.removeEventListener("abort", onAbort);
+      reject(new DOMException("Upload aborted", "AbortError"));
+    });
+    const formData = new FormData();
+    for (const [k, v] of Object.entries(fields)) {
+      formData.append(k, v);
+    }
+    formData.append("file", file);
+    xhr.open("POST", url);
+    xhr.send(formData);
+  });
+}
+function uploadPut(file, url, headers, onProgress, signal) {
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    const onAbort = () => {
+      xhr.abort();
+      reject(new DOMException("Upload aborted", "AbortError"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    xhr.upload.addEventListener("progress", (e) => {
+      if (e.lengthComputable) {
+        onProgress?.({
+          loaded: e.loaded,
+          total: e.total,
+          percent: Math.round(e.loaded / e.total * 100)
+        });
+      }
+    });
+    xhr.addEventListener("load", () => {
+      signal?.removeEventListener("abort", onAbort);
+      if (xhr.status >= 200 && xhr.status < 300) {
+        onProgress?.({ loaded: file.size, total: file.size, percent: 100 });
+        resolve();
+      } else {
+        reject(new Error(`Upload failed: ${xhr.status} ${xhr.statusText}`));
+      }
+    });
+    xhr.addEventListener("error", () => {
+      signal?.removeEventListener("abort", onAbort);
+      reject(new Error("Upload failed: network error"));
+    });
+    xhr.addEventListener("abort", () => {
+      signal?.removeEventListener("abort", onAbort);
+      reject(new DOMException("Upload aborted", "AbortError"));
+    });
+    xhr.open("PUT", url);
+    for (const [k, v] of Object.entries(headers)) {
+      xhr.setRequestHeader(k, v);
+    }
+    xhr.send(file);
+  });
+}
+
+// src/upload/part.ts
+function uploadPart(blob, presignedUrl, partLoaded, totalSize, reportProgress, signal) {
+  return new Promise((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    const onAbort = () => {
+      xhr.abort();
+      reject(new DOMException("Upload aborted", "AbortError"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+    xhr.upload.addEventListener("progress", (e) => {
+      if (e.lengthComputable) {
+        partLoaded.bytes = e.loaded;
+        reportProgress();
+      }
+    });
+    xhr.addEventListener("load", () => {
+      signal?.removeEventListener("abort", onAbort);
+      if (xhr.status >= 200 && xhr.status < 300) {
+        partLoaded.bytes = blob.size;
+        reportProgress();
+        resolve();
+      } else {
+        reject(new Error(`Part upload failed: ${xhr.status}`));
+      }
+    });
+    xhr.addEventListener("error", () => {
+      signal?.removeEventListener("abort", onAbort);
+      reject(new Error("Part upload failed: network error"));
+    });
+    xhr.addEventListener("abort", () => {
+      signal?.removeEventListener("abort", onAbort);
+      reject(new DOMException("Upload aborted", "AbortError"));
+    });
+    xhr.open("PUT", presignedUrl);
+    xhr.send(blob);
+  });
+}
+
+// src/upload/multipart.ts
+function resolvePartSize(partIndex, totalParts, partSize, fileSize) {
+  return partIndex === totalParts - 1 ? fileSize - partIndex * partSize : partSize;
+}
+async function uploadMultipart(api, file, objectKey, partSize, concurrentParts, onProgress, signal, requestOptions, retryConfig, uploadStore, onPartUpload, onMultipartInit) {
+  const bucket = requestOptions?.bucket;
+  const contentType = requestOptions?.contentType ?? file.type;
+  const store = uploadStore != null && uploadStore !== false ? uploadStore : null;
+  let uploadId;
+  let key;
+  const completedPartNumbers = /* @__PURE__ */ new Set();
+  const existing = store ? await store.get(objectKey, file.size) : null;
+  if (existing) {
+    try {
+      const { parts: parts2 } = await api.multipart.listParts({
+        key: existing.key,
+        uploadId: existing.uploadId,
+        bucket: bucket ?? existing.bucket
+      });
+      uploadId = existing.uploadId;
+      key = existing.key;
+      for (const p of parts2) completedPartNumbers.add(p.partNumber);
+      onMultipartInit?.(uploadId, key);
+    } catch {
+      await store?.delete(objectKey);
+      const result = await api.multipart.init({
+        key: objectKey,
+        contentType,
+        fileSize: file.size,
+        fileName: requestOptions?.fileName !== null ? requestOptions?.fileName ?? file.name : void 0,
+        metadata: requestOptions?.metadata,
+        bucket,
+        acl: requestOptions?.acl
+      });
+      uploadId = result.uploadId;
+      key = result.key;
+      await store?.set({ uploadId, key, fileSize: file.size, bucket });
+      onMultipartInit?.(uploadId, key);
+    }
+  } else {
+    const result = await api.multipart.init({
+      key: objectKey,
+      contentType,
+      fileSize: file.size,
+      fileName: requestOptions?.fileName !== null ? requestOptions?.fileName ?? file.name : void 0,
+      metadata: requestOptions?.metadata,
+      bucket,
+      acl: requestOptions?.acl
+    });
+    uploadId = result.uploadId;
+    key = result.key;
+    await store?.set({ uploadId, key, fileSize: file.size, bucket });
+    onMultipartInit?.(uploadId, key);
+  }
+  const totalParts = Math.ceil(file.size / partSize);
+  const partProgress = Array.from(
+    { length: totalParts },
+    (_, i) => ({
+      bytes: completedPartNumbers.has(i + 1) ? resolvePartSize(i, totalParts, partSize, file.size) : 0
+    })
+  );
+  const parts = Array.from(
+    completedPartNumbers,
+    (n) => ({ partNumber: n })
+  );
+  const reportProgress = () => {
+    const loaded = partProgress.reduce((sum, p) => sum + p.bytes, 0);
+    onProgress?.({
+      loaded,
+      total: file.size,
+      percent: Math.round(loaded / file.size * 100)
+    });
+  };
+  if (completedPartNumbers.size > 0) {
+    reportProgress();
+  }
+  try {
+    for (let batchStart = 0; batchStart < totalParts; batchStart += concurrentParts) {
+      if (signal?.aborted) {
+        throw new DOMException("Upload aborted", "AbortError");
+      }
+      const batchEnd = Math.min(batchStart + concurrentParts, totalParts);
+      const batch = [];
+      for (let i = batchStart; i < batchEnd; i++) {
+        const partNumber = i + 1;
+        if (completedPartNumbers.has(partNumber)) continue;
+        const start = i * partSize;
+        const end = Math.min(start + partSize, file.size);
+        const blob = file.slice(start, end);
+        batch.push(
+          withRetry(
+            async () => {
+              const { presignedUrl } = await api.multipart.signPart({
+                key,
+                uploadId,
+                partNumber,
+                partSize: blob.size,
+                bucket
+              });
+              partProgress[i].bytes = 0;
+              await uploadPart(
+                blob,
+                presignedUrl,
+                partProgress[i],
+                file.size,
+                reportProgress,
+                signal
+              );
+              onPartUpload?.(partNumber, totalParts);
+              return { partNumber };
+            },
+            retryConfig,
+            signal
+          )
+        );
+      }
+      const batchResults = await Promise.all(batch);
+      parts.push(...batchResults);
+    }
+    parts.sort((a, b) => a.partNumber - b.partNumber);
+    const result = await api.multipart.complete({
+      key,
+      uploadId,
+      parts,
+      bucket
+    });
+    await store?.delete(objectKey);
+    onProgress?.({ loaded: file.size, total: file.size, percent: 100 });
+    return result.eTag;
+  } catch (err) {
+    if (store === null) {
+      api.multipart.abort({ key, uploadId, bucket }).catch(() => {
+      });
+    }
+    throw err;
+  }
+}
+
+// src/upload/upload-file.ts
+async function uploadFile(api, file, objectKey, config = {}, callbacks = {}, signal, requestOptions) {
+  const threshold = config.multipartThreshold ?? DEFAULT_MULTIPART_THRESHOLD;
+  const useMultipart = config.multipart === true && file.size >= threshold;
+  const concurrentParts = config.concurrentParts ?? DEFAULT_CONCURRENT_PARTS;
+  const partSize = requestOptions?.partSize ?? config.partSize ?? DEFAULT_PART_SIZE;
+  const contentType = requestOptions?.contentType ?? file.type;
+  let eTag;
+  if (useMultipart) {
+    callbacks.onPhaseChange?.("uploading");
+    eTag = await uploadMultipart(
+      api,
+      file,
+      objectKey,
+      partSize,
+      concurrentParts,
+      callbacks.onProgress,
+      signal,
+      requestOptions,
+      config.retry,
+      config.uploadStore,
+      callbacks.onPartUpload,
+      callbacks.onMultipartInit
+    );
+  } else {
+    await withRetry(
+      async () => {
+        callbacks.onPhaseChange?.("presigning");
+        const presign = await api.upload({
+          key: objectKey,
+          contentType,
+          fileSize: file.size,
+          fileName: requestOptions?.fileName !== null ? requestOptions?.fileName ?? file.name : void 0,
+          metadata: requestOptions?.metadata,
+          bucket: requestOptions?.bucket,
+          acl: requestOptions?.acl
+        });
+        callbacks.onPhaseChange?.("uploading");
+        if (presign.method === "put") {
+          await uploadPut(
+            file,
+            presign.url,
+            presign.headers ?? {},
+            callbacks.onProgress,
+            signal
+          );
+        } else {
+          await uploadSimple(
+            file,
+            presign.url,
+            presign.fields ?? {},
+            callbacks.onProgress,
+            signal
+          );
+        }
+      },
+      config.retry,
+      signal
+    );
+    callbacks.onPhaseChange?.("finalizing");
+    const confirmed = await api.confirm({
+      key: objectKey,
+      bucket: requestOptions?.bucket
+    });
+    eTag = confirmed.eTag;
+  }
+  return { key: objectKey, eTag };
+}
+
+// src/upload/upload-files.ts
+async function uploadFiles(api, items, config = {}, callbacks = {}, signal, getRequestOptions) {
+  const results = items.map((item) => ({
+    ...item,
+    status: "pending",
+    progress: { loaded: 0, total: item.file.size, percent: 0 },
+    result: null,
+    error: null
+  }));
+  const reportTotalProgress = () => {
+    const loaded = results.reduce((sum, r) => sum + r.progress.loaded, 0);
+    const total = results.reduce((sum, r) => sum + r.progress.total, 0);
+    callbacks.onTotalProgress?.({
+      loaded,
+      total,
+      percent: total > 0 ? Math.round(loaded / total * 100) : 0
+    });
+  };
+  let nextIndex = 0;
+  const processNext = async () => {
+    while (nextIndex < results.length) {
+      if (signal?.aborted) return;
+      const idx = nextIndex++;
+      const item = results[idx];
+      item.status = "uploading";
+      try {
+        const result = await uploadFile(
+          api,
+          item.file,
+          item.objectKey,
+          config,
+          {
+            onProgress: (progress) => {
+              item.progress = progress;
+              callbacks.onFileProgress?.(item.id, progress);
+              reportTotalProgress();
+            }
+          },
+          signal,
+          getRequestOptions?.(item.file)
+        );
+        item.status = "success";
+        item.result = result;
+        item.progress = {
+          loaded: item.file.size,
+          total: item.file.size,
+          percent: 100
+        };
+        callbacks.onFileSuccess?.(item.id, result);
+        reportTotalProgress();
+      } catch (err) {
+        if (err.name === "AbortError") {
+          item.status = "error";
+          item.error = "Upload cancelled";
+          return;
+        }
+        const message = err instanceof Error ? err.message : "Upload failed";
+        item.status = "error";
+        item.error = message;
+        callbacks.onFileError?.(item.id, message);
+        reportTotalProgress();
+      }
+    }
+  };
+  const concurrentFiles = config.concurrentFiles ?? DEFAULT_CONCURRENT_FILES;
+  const workers = Array.from(
+    { length: Math.min(concurrentFiles, items.length) },
+    () => processNext()
+  );
+  await Promise.all(workers);
+  return results;
+}
+
+// src/helpers/format-file-size.ts
+function formatFileSize(bytes) {
+  if (bytes === 0) return "0 B";
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  const size = bytes / Math.pow(1024, i);
+  return `${size.toFixed(i === 0 ? 0 : 1)} ${units[i]}`;
+}
+
+// src/helpers/validate-file.ts
+function validateFile(file, options) {
+  if (options.accept?.length) {
+    const allowed = options.accept.some((type) => {
+      if (type.startsWith(".")) {
+        return file.name.toLowerCase().endsWith(type.toLowerCase());
+      }
+      if (type.endsWith("/*")) {
+        return file.type.startsWith(type.replace("/*", "/"));
+      }
+      return file.type === type;
+    });
+    if (!allowed) {
+      const ext = file.name.includes(".") ? file.name.split(".").pop() : null;
+      return `File type "${ext ? `.${ext}` : file.type || "unknown"}" is not allowed`;
+    }
+  }
+  if (file.size === 0) {
+    return "File is empty";
+  }
+  if (options.maxFileSize && file.size > options.maxFileSize) {
+    const maxMB = (options.maxFileSize / (1024 * 1024)).toFixed(1);
+    return `File size exceeds ${maxMB} MB limit`;
+  }
+  return null;
+}
+
+// src/helpers/parse-content-disposition.ts
+function parseContentDispositionFilename(header, fallback) {
+  if (!header) return fallback;
+  const starMatch = header.match(/filename\*=UTF-8''([^;,\s]+)/i);
+  if (starMatch) {
+    try {
+      return decodeURIComponent(starMatch[1]);
+    } catch {
+    }
+  }
+  const match = header.match(/filename="([^"]+)"/i);
+  if (match) return match[1];
+  return fallback;
+}
+
+// src/helpers/format-upload-progress.ts
+function formatUploadProgress(loaded, total, percent) {
+  const loadedStr = formatFileSize(loaded);
+  if (!total) return loadedStr;
+  return `${loadedStr} / ${formatFileSize(total)} (${Math.round(percent)}%)`;
+}
+
+// src/helpers/format-speed.ts
+function formatSpeed(bytesPerSecond) {
+  return `${formatFileSize(bytesPerSecond)}/s`;
+}
+
+// src/helpers/format-eta.ts
+function formatEta(remainingBytes, bytesPerSecond) {
+  if (bytesPerSecond <= 0 || remainingBytes <= 0) return null;
+  const totalSeconds = remainingBytes / bytesPerSecond;
+  if (totalSeconds < 60) return `${Math.ceil(totalSeconds)}s`;
+  const totalMinutes = totalSeconds / 60;
+  if (totalMinutes < 60) return `${Math.ceil(totalMinutes)}m`;
+  const hours = Math.floor(totalMinutes / 60);
+  const mins = Math.ceil(totalMinutes % 60);
+  return mins > 0 ? `${hours}h ${mins}m` : `${hours}h`;
+}
+
+// src/helpers/build-object-key.ts
+function buildObjectKey(...parts) {
+  return parts.map((p) => p.replace(/^\/+|\/+$/g, "")).filter(Boolean).join("/");
+}
+
+// src/helpers/get-file-extension.ts
+function getFileExtension(filename) {
+  const dotIndex = filename.lastIndexOf(".");
+  if (dotIndex < 1) return "";
+  return filename.slice(dotIndex + 1).toLowerCase();
+}
+
+// src/helpers/truncate-filename.ts
+function truncateFilename(name, maxChars = 26) {
+  if (name.length <= maxChars) return name;
+  const dotIndex = name.lastIndexOf(".");
+  if (dotIndex <= 0) {
+    return name.slice(0, maxChars - 1) + "\u2026";
+  }
+  const ext = name.slice(dotIndex);
+  const available = maxChars - ext.length - 1;
+  if (available <= 0) {
+    return name.slice(0, maxChars - 1) + "\u2026";
+  }
+  return name.slice(0, available) + "\u2026 " + ext;
+}
+
+// src/helpers/speed-tracker.ts
+function createSpeedTracker(windowMs = 3e3) {
+  const samples = [];
+  return {
+    /**
+     * Record the latest cumulative `loaded` byte count.
+     * Returns the current speed in bytes/second (0 until at least 2 samples exist).
+     */
+    update(loaded) {
+      const now = Date.now();
+      samples.push({ t: now, loaded });
+      const cutoff = now - windowMs;
+      while (samples.length > 1 && samples[0].t < cutoff) {
+        samples.shift();
+      }
+      if (samples.length < 2) return 0;
+      const oldest = samples[0];
+      const newest = samples[samples.length - 1];
+      const deltaMs = newest.t - oldest.t;
+      const deltaBytes = newest.loaded - oldest.loaded;
+      return deltaMs > 0 ? Math.round(deltaBytes / deltaMs * 1e3) : 0;
+    },
+    reset() {
+      samples.length = 0;
+    }
+  };
+}
+function useLiveRef(value) {
+  const ref = useRef(value);
+  ref.current = value;
+  return ref;
+}
+
+// src/hooks/use-upload.ts
+var INITIAL_PROGRESS = { loaded: 0, total: 0, percent: 0 };
+var INITIAL_STATE = {
+  phase: "idle",
+  progress: INITIAL_PROGRESS,
+  error: null,
+  result: null,
+  fileName: null,
+  fileSize: null
+};
+function useUpload(options) {
+  const [state, setState] = useState(INITIAL_STATE);
+  const contextApi = useContext(S3Context);
+  const optsRef = useLiveRef(options);
+  const apiRef = useLiveRef(contextApi);
+  const abortRef = useRef(null);
+  const activeUploadRef = useRef(null);
+  const detachingRef = useRef(false);
+  const speedTrackerRef = useRef(createSpeedTracker());
+  const lastSpeedRef = useRef(void 0);
+  const lastSpeedUpdateRef = useRef(0);
+  const upload = useCallback(
+    async (file, objectKey, requestOptions) => {
+      setState({
+        ...INITIAL_STATE,
+        phase: "validating",
+        fileName: file.name,
+        fileSize: file.size
+      });
+      const opts = optsRef.current;
+      const api = opts.api ?? apiRef.current;
+      if (!api)
+        throw new Error(
+          "[better-s3] No S3Api client found. Pass `api` to useUpload or wrap with <S3Provider>."
+        );
+      const validationError = validateFile(file, {
+        accept: opts.accept,
+        maxFileSize: opts.maxFileSize
+      });
+      if (validationError) {
+        setState((s) => ({ ...s, phase: "error", error: validationError }));
+        opts.onError?.(file, new Error(validationError), "validating");
+        return;
+      }
+      if (opts.beforeUpload) {
+        const allowed = await opts.beforeUpload(file);
+        if (!allowed) {
+          setState((s) => ({
+            ...s,
+            phase: "error",
+            error: "Upload blocked by beforeUpload hook"
+          }));
+          opts.onError?.(file, new Error("blocked"), "validating");
+          return;
+        }
+      }
+      speedTrackerRef.current.reset();
+      lastSpeedRef.current = void 0;
+      lastSpeedUpdateRef.current = 0;
+      setState((s) => ({ ...s, phase: "presigning" }));
+      opts.onUploadStart?.(file, objectKey);
+      const controller = new AbortController();
+      abortRef.current = controller;
+      activeUploadRef.current = {
+        file,
+        objectKey,
+        serverKey: objectKey,
+        bucket: requestOptions?.bucket,
+        requestOptions
+      };
+      try {
+        const result = await uploadFile(
+          api,
+          file,
+          objectKey,
+          {
+            multipart: opts.multipart,
+            multipartThreshold: opts.multipartThreshold,
+            concurrentParts: opts.concurrentParts,
+            partSize: opts.partSize,
+            retry: opts.retry,
+            uploadStore: opts.uploadStore
+          },
+          {
+            onProgress: (progress) => {
+              const rawSpeed = speedTrackerRef.current.update(progress.loaded);
+              const now = Date.now();
+              if (rawSpeed > 0 && now - lastSpeedUpdateRef.current >= 500) {
+                lastSpeedRef.current = rawSpeed;
+                lastSpeedUpdateRef.current = now;
+              }
+              const speed = lastSpeedRef.current;
+              const p = speed ? { ...progress, speed } : progress;
+              setState((s) => ({ ...s, progress: p }));
+              opts.onProgress?.(file, p);
+            },
+            onPhaseChange: (phase) => setState((s) => ({ ...s, phase })),
+            onPartUpload: (partNumber, totalParts) => opts.onPartUpload?.(file, partNumber, totalParts),
+            onMultipartInit: (uploadId, serverKey) => {
+              if (activeUploadRef.current) {
+                activeUploadRef.current.uploadId = uploadId;
+                activeUploadRef.current.serverKey = serverKey;
+              }
+              opts.onMultipartInit?.(file, uploadId);
+            }
+          },
+          controller.signal,
+          requestOptions
+        );
+        setState((s) => ({
+          ...s,
+          phase: "success",
+          result,
+          progress: { loaded: file.size, total: file.size, percent: 100 }
+        }));
+        await opts.onSuccess?.(file, result);
+      } catch (err) {
+        if (err.name === "AbortError") {
+          if (detachingRef.current) {
+            detachingRef.current = false;
+            return;
+          }
+          opts.onCancel?.(file);
+          setState(INITIAL_STATE);
+          return;
+        }
+        const message = err instanceof Error ? err.message : "Upload failed";
+        setState((s) => ({ ...s, phase: "error", error: message }));
+        opts.onError?.(file, err, "uploading");
+      } finally {
+        abortRef.current = null;
+        activeUploadRef.current = null;
+      }
+    },
+    []
+  );
+  const cancel = useCallback(() => {
+    const opts = optsRef.current;
+    const api = opts.api ?? apiRef.current;
+    const active = activeUploadRef.current;
+    abortRef.current?.abort();
+    if (active && api) {
+      const { objectKey, serverKey, uploadId, bucket } = active;
+      const store = opts.uploadStore;
+      if (store != null && store !== false) {
+        void Promise.resolve(store.delete(objectKey)).catch(() => {
+        });
+      }
+      if (uploadId) {
+        api.multipart.abort({ key: serverKey, uploadId, bucket }).catch(() => {
+        });
+      }
+    }
+    setState(INITIAL_STATE);
+  }, []);
+  const detach = useCallback(() => {
+    const active = activeUploadRef.current;
+    if (!active) return;
+    detachingRef.current = true;
+    abortRef.current?.abort();
+    setState(INITIAL_STATE);
+  }, []);
+  const reset = useCallback(() => {
+    abortRef.current?.abort();
+    setState(INITIAL_STATE);
+  }, []);
+  return { ...state, upload, cancel, detach, reset };
+}
+var INITIAL_PROGRESS2 = { loaded: 0, total: 0, percent: 0 };
+var INITIAL_STATE2 = {
+  phase: "idle",
+  files: [],
+  totalProgress: INITIAL_PROGRESS2,
+  error: null
+};
+function generateId() {
+  return crypto.randomUUID();
+}
+function useMultiUpload(options) {
+  const [state, setState] = useState(INITIAL_STATE2);
+  const contextApi = useContext(S3Context);
+  const optsRef = useLiveRef(options);
+  const apiRef = useLiveRef(contextApi);
+  const abortRef = useRef(null);
+  const resettingRef = useRef(false);
+  const fileMapRef = useRef(/* @__PURE__ */ new Map());
+  const fileSpeedTrackersRef = useRef(/* @__PURE__ */ new Map());
+  const totalSpeedTrackerRef = useRef(createSpeedTracker());
+  const fileLastSpeedRef = useRef(/* @__PURE__ */ new Map());
+  const fileLastSpeedUpdateRef = useRef(/* @__PURE__ */ new Map());
+  const lastTotalSpeedRef = useRef(void 0);
+  const lastTotalSpeedUpdateRef = useRef(0);
+  const upload = useCallback(
+    async (files, resolveKey) => {
+      const opts = optsRef.current;
+      const api = opts.api ?? apiRef.current;
+      if (!api)
+        throw new Error(
+          "[better-s3] No S3Api client found. Pass `api` to useMultiUpload or wrap with <S3Provider>."
+        );
+      const items = [];
+      const fileStates = [];
+      const fileMap = /* @__PURE__ */ new Map();
+      setState((s) => ({ ...s, phase: "validating", error: null }));
+      if (opts.maxFiles && files.length > opts.maxFiles) {
+        const msg = `Too many files. Maximum is ${opts.maxFiles}.`;
+        setState((s) => ({ ...s, phase: "error", error: msg }));
+        opts.onError?.(new Error(msg));
+        return;
+      }
+      for (const file of files) {
+        const validationError = validateFile(file, {
+          accept: opts.accept,
+          maxFileSize: opts.maxFileSize
+        });
+        if (validationError) {
+          const msg = `${file.name}: ${validationError}`;
+          setState((s) => ({ ...s, phase: "error", error: msg }));
+          opts.onError?.(new Error(msg));
+          return;
+        }
+      }
+      if (opts.beforeUpload) {
+        const allowed = await opts.beforeUpload(files);
+        if (!allowed) {
+          setState((s) => ({
+            ...s,
+            phase: "error",
+            error: "Upload blocked by beforeUpload hook"
+          }));
+          opts.onError?.(new Error("blocked"));
+          return;
+        }
+      }
+      for (const file of files) {
+        const id = generateId();
+        const objectKey = resolveKey(file);
+        items.push({ id, file, objectKey });
+        fileMap.set(id, file);
+        fileStates.push({
+          id,
+          fileName: file.name,
+          fileSize: file.size,
+          status: "pending",
+          progress: { loaded: 0, total: file.size, percent: 0 },
+          error: null
+        });
+      }
+      fileMapRef.current = fileMap;
+      setState({
+        phase: "uploading",
+        files: fileStates,
+        totalProgress: {
+          loaded: 0,
+          total: files.reduce((s, f) => s + f.size, 0),
+          percent: 0
+        },
+        error: null
+      });
+      opts.onUploadStart?.(files);
+      fileSpeedTrackersRef.current.clear();
+      for (const item of items) {
+        fileSpeedTrackersRef.current.set(item.id, createSpeedTracker());
+      }
+      totalSpeedTrackerRef.current.reset();
+      fileLastSpeedRef.current.clear();
+      fileLastSpeedUpdateRef.current.clear();
+      lastTotalSpeedRef.current = void 0;
+      lastTotalSpeedUpdateRef.current = 0;
+      const controller = new AbortController();
+      abortRef.current = controller;
+      try {
+        const results = await uploadFiles(
+          api,
+          items,
+          {
+            multipart: opts.multipart,
+            multipartThreshold: opts.multipartThreshold,
+            concurrentParts: opts.concurrentParts,
+            concurrentFiles: opts.concurrentFiles,
+            partSize: opts.partSize,
+            retry: opts.retry,
+            uploadStore: opts.uploadStore
+          },
+          {
+            onFileProgress: (id, progress) => {
+              const tracker = fileSpeedTrackersRef.current.get(id);
+              const rawSpeed = tracker ? tracker.update(progress.loaded) : 0;
+              const now = Date.now();
+              if (rawSpeed > 0 && now - (fileLastSpeedUpdateRef.current.get(id) ?? 0) >= 500) {
+                fileLastSpeedRef.current.set(id, rawSpeed);
+                fileLastSpeedUpdateRef.current.set(id, now);
+              }
+              const speed = fileLastSpeedRef.current.get(id);
+              const p = speed ? { ...progress, speed } : progress;
+              setState((s) => ({
+                ...s,
+                files: s.files.map(
+                  (f) => f.id === id ? { ...f, status: "uploading", progress: p } : f
+                )
+              }));
+              const file = fileMap.get(id);
+              if (file) opts.onFileProgress?.(file, p);
+            },
+            onFileSuccess: (id, result) => {
+              setState((s) => ({
+                ...s,
+                files: s.files.map(
+                  (f) => f.id === id ? {
+                    ...f,
+                    status: "success",
+                    progress: {
+                      loaded: f.fileSize,
+                      total: f.fileSize,
+                      percent: 100
+                    }
+                  } : f
+                )
+              }));
+              const file = fileMap.get(id);
+              if (file) opts.onFileSuccess?.(file, result);
+            },
+            onFileError: (id, error) => {
+              setState((s) => ({
+                ...s,
+                files: s.files.map(
+                  (f) => f.id === id ? { ...f, status: "error", error } : f
+                )
+              }));
+              const file = fileMap.get(id);
+              if (file) opts.onFileError?.(file, error);
+            },
+            onTotalProgress: (progress) => {
+              const rawSpeed = totalSpeedTrackerRef.current.update(
+                progress.loaded
+              );
+              const now = Date.now();
+              if (rawSpeed > 0 && now - lastTotalSpeedUpdateRef.current >= 1e3) {
+                lastTotalSpeedRef.current = rawSpeed;
+                lastTotalSpeedUpdateRef.current = now;
+              }
+              const speed = lastTotalSpeedRef.current;
+              const p = speed ? { ...progress, speed } : progress;
+              setState((s) => ({ ...s, totalProgress: p }));
+              opts.onProgress?.(p);
+            }
+          },
+          controller.signal,
+          (file) => {
+            const perFile = opts.getUploadOptions?.(file);
+            if (!opts.uploadOptions) return perFile ?? {};
+            return { ...opts.uploadOptions, ...perFile };
+          }
+        );
+        const hasErrors = results.some((r) => r.status === "error");
+        const successResults = results.filter((r) => r.result !== null).map((r) => r.result);
+        setState((s) => ({
+          ...s,
+          phase: hasErrors ? "error" : "success",
+          error: hasErrors ? `${results.filter((r) => r.status === "error").length} file(s) failed` : null,
+          totalProgress: hasErrors ? s.totalProgress : {
+            loaded: s.totalProgress.total,
+            total: s.totalProgress.total,
+            percent: 100
+          }
+        }));
+        if (!hasErrors) {
+          await opts.onSuccess?.(successResults);
+        }
+      } catch (err) {
+        if (err.name === "AbortError") {
+          if (!resettingRef.current) opts.onCancel?.();
+          resettingRef.current = false;
+          setState(INITIAL_STATE2);
+          return;
+        }
+        const message = err instanceof Error ? err.message : "Upload failed";
+        setState((s) => ({ ...s, phase: "error", error: message }));
+        opts.onError?.(err);
+      } finally {
+        abortRef.current = null;
+      }
+    },
+    []
+  );
+  const cancel = useCallback(() => {
+    abortRef.current?.abort();
+    setState(INITIAL_STATE2);
+  }, []);
+  const reset = useCallback(() => {
+    resettingRef.current = true;
+    abortRef.current?.abort();
+    setState(INITIAL_STATE2);
+  }, []);
+  return { ...state, upload, cancel, reset };
+}
+function useUploadControls(options) {
+  const single = useUpload(options);
+  const inputRef = useRef(null);
+  const [fileInfo, setFileInfo] = useState(null);
+  const resolveKey = (file) => typeof options.objectKey === "function" ? options.objectKey(file) : options.objectKey;
+  const handleFiles = async (files) => {
+    const file = files?.[0];
+    if (!file) return;
+    setFileInfo({ name: file.name, size: file.size });
+    await single.upload(file, resolveKey(file), {
+      ...options.uploadOptions,
+      ...options.getUploadOptions?.(file)
+    });
+  };
+  return {
+    phase: single.phase,
+    fileInfo,
+    progress: single.progress,
+    error: single.error,
+    isUploading: single.phase === "uploading",
+    handleFiles,
+    openFilePicker: () => inputRef.current?.click(),
+    cancel: single.cancel,
+    detach: single.detach,
+    reset: () => {
+      single.reset();
+      setFileInfo(null);
+    },
+    inputProps: {
+      ref: inputRef,
+      type: "file",
+      accept: options.accept?.join(","),
+      hidden: true,
+      onChange: (e) => {
+        handleFiles(e.target.files);
+        e.target.value = "";
+      }
+    },
+    dropHandlers: {
+      onDragOver: (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+      },
+      onDrop: (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        if (single.phase !== "uploading") handleFiles(e.dataTransfer.files);
+      }
+    }
+  };
+}
+function useMultiUploadControls(options) {
+  const multi = useMultiUpload(options);
+  const inputRef = useRef(null);
+  const resolveKey = (file) => typeof options.objectKey === "function" ? options.objectKey(file) : options.objectKey;
+  const handleFiles = async (files) => {
+    if (!files?.length) return;
+    await multi.upload(Array.from(files), resolveKey);
+  };
+  return {
+    phase: multi.phase,
+    files: multi.files,
+    totalProgress: multi.totalProgress,
+    error: multi.error,
+    isUploading: multi.phase === "uploading",
+    handleFiles,
+    openFilePicker: () => inputRef.current?.click(),
+    cancel: multi.cancel,
+    reset: multi.reset,
+    inputProps: {
+      ref: inputRef,
+      type: "file",
+      multiple: true,
+      accept: options.accept?.join(","),
+      hidden: true,
+      onChange: (e) => {
+        handleFiles(e.target.files);
+        e.target.value = "";
+      }
+    },
+    dropHandlers: {
+      onDragOver: (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+      },
+      onDrop: (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        if (multi.phase !== "uploading") handleFiles(e.dataTransfer.files);
+      }
+    }
+  };
+}
+var INITIAL_STATE3 = {
+  phase: "idle",
+  error: null,
+  url: null,
+  expiresIn: null
+};
+function useDownload(options) {
+  const [state, setState] = useState(INITIAL_STATE3);
+  const contextApi = useContext(S3Context);
+  const optsRef = useLiveRef(options);
+  const apiRef = useLiveRef(contextApi);
+  const presign = useCallback(async (key, downloadName) => {
+    const opts = optsRef.current;
+    const api = opts.api ?? apiRef.current;
+    if (!api)
+      throw new Error(
+        "[better-s3] No S3Api client found. Pass `api` to useDownload or wrap with <S3Provider>."
+      );
+    setState({ phase: "presigning", error: null, url: null, expiresIn: null });
+    try {
+      const result = await api.download(key, {
+        fileName: downloadName,
+        bucket: opts.bucket
+      });
+      setState({
+        phase: "idle",
+        error: null,
+        url: result.url,
+        expiresIn: result.expiresIn
+      });
+      return { url: result.url, expiresIn: result.expiresIn };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Download failed";
+      setState({ phase: "error", error: message, url: null, expiresIn: null });
+      opts.onError?.(key, err);
+      return null;
+    }
+  }, []);
+  const download = useCallback(
+    async (key, downloadName) => {
+      const opts = optsRef.current;
+      if (opts.beforeDownload) {
+        const allowed = await opts.beforeDownload(key);
+        if (!allowed) {
+          setState({
+            phase: "error",
+            error: "Download blocked by beforeDownload hook",
+            url: null,
+            expiresIn: null
+          });
+          opts.onError?.(key, new Error("blocked"));
+          return;
+        }
+      }
+      const result = await presign(key, downloadName);
+      if (!result) return;
+      window.location.href = result.url;
+      opts.onInitiated?.(key);
+    },
+    [presign]
+  );
+  const reset = useCallback(() => setState(INITIAL_STATE3), []);
+  return { ...state, download, presign, reset };
+}
+var INITIAL_PROGRESS3 = { loaded: 0, total: 0, percent: 0 };
+var INITIAL_STATE4 = {
+  phase: "idle",
+  progress: INITIAL_PROGRESS3,
+  error: null,
+  fileName: null,
+  fileSize: null
+};
+function useFetchDownload(options) {
+  const [state, setState] = useState(INITIAL_STATE4);
+  const contextApi = useContext(S3Context);
+  const optsRef = useLiveRef(options);
+  const apiRef = useLiveRef(contextApi);
+  const abortRef = useRef(null);
+  const resettingRef = useRef(false);
+  const speedTrackerRef = useRef(createSpeedTracker());
+  const lastSpeedRef = useRef(void 0);
+  const lastSpeedUpdateRef = useRef(0);
+  const download = useCallback(async (key, downloadName) => {
+    const fallback = key.split("/").pop() ?? key;
+    const opts = optsRef.current;
+    const api = opts.api ?? apiRef.current;
+    if (!api)
+      throw new Error(
+        "[better-s3] No S3Api client found. Pass `api` to useFetchDownload or wrap with <S3Provider>."
+      );
+    if (opts.beforeDownload) {
+      const allowed = await opts.beforeDownload(key);
+      if (!allowed) {
+        setState((s) => ({
+          ...s,
+          phase: "error",
+          error: "Download blocked by beforeDownload hook"
+        }));
+        opts.onError?.(key, new Error("blocked"), "presigning");
+        return;
+      }
+    }
+    setState({
+      phase: "presigning",
+      progress: INITIAL_PROGRESS3,
+      error: null,
+      fileName: downloadName ?? null,
+      fileSize: null
+    });
+    try {
+      const { url } = await api.download(key, {
+        fileName: downloadName,
+        bucket: opts.bucket
+      });
+      setState((s) => ({ ...s, phase: "downloading" }));
+      opts.onDownloadStart?.(key);
+      speedTrackerRef.current.reset();
+      lastSpeedRef.current = void 0;
+      lastSpeedUpdateRef.current = 0;
+      const controller = new AbortController();
+      abortRef.current = controller;
+      const res = await fetch(url, { signal: controller.signal });
+      if (!res.ok) {
+        throw new Error(
+          res.status === 404 ? "File not found" : `Download failed (${res.status})`
+        );
+      }
+      const contentLength = Number(res.headers.get("content-length") || 0);
+      const name = downloadName ?? parseContentDispositionFilename(
+        res.headers.get("content-disposition"),
+        fallback
+      );
+      setState((s) => ({
+        ...s,
+        fileName: name,
+        fileSize: contentLength || null
+      }));
+      const reader = res.body?.getReader();
+      if (!reader) throw new Error("ReadableStream not supported");
+      const chunks = [];
+      let loaded = 0;
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        chunks.push(value);
+        loaded += value.byteLength;
+        const percent = contentLength > 0 ? Math.round(loaded / contentLength * 100) : 0;
+        const rawSpeed = speedTrackerRef.current.update(loaded);
+        const now = Date.now();
+        if (rawSpeed > 0 && now - lastSpeedUpdateRef.current >= 500) {
+          lastSpeedRef.current = rawSpeed;
+          lastSpeedUpdateRef.current = now;
+        }
+        const speed = lastSpeedRef.current;
+        const progress = {
+          loaded,
+          total: contentLength,
+          percent,
+          ...speed && { speed }
+        };
+        setState((s) => ({ ...s, progress }));
+        opts.onProgress?.(key, progress);
+      }
+      const blob = new Blob(chunks);
+      const blobUrl = URL.createObjectURL(blob);
+      const anchor = document.createElement("a");
+      anchor.href = blobUrl;
+      anchor.download = name ?? fallback;
+      anchor.click();
+      URL.revokeObjectURL(blobUrl);
+      setState((s) => ({
+        ...s,
+        phase: "success",
+        fileSize: blob.size,
+        progress: { loaded: blob.size, total: blob.size, percent: 100 }
+      }));
+      await opts.onSuccess?.(key, name ?? fallback);
+    } catch (err) {
+      if (err.name === "AbortError") {
+        if (!resettingRef.current) opts.onCancel?.(key);
+        resettingRef.current = false;
+        setState(INITIAL_STATE4);
+        return;
+      }
+      const message = err instanceof Error ? err.message : "Download failed";
+      setState((s) => ({ ...s, phase: "error", error: message }));
+      opts.onError?.(key, err, "downloading");
+    } finally {
+      abortRef.current = null;
+    }
+  }, []);
+  const cancel = useCallback(() => {
+    abortRef.current?.abort();
+    setState(INITIAL_STATE4);
+  }, []);
+  const reset = useCallback(() => {
+    resettingRef.current = true;
+    abortRef.current?.abort();
+    setState(INITIAL_STATE4);
+  }, []);
+  return { ...state, download, cancel, reset };
+}
+var INITIAL_STATE5 = {
+  phase: "idle",
+  error: null,
+  pendingKey: null
+};
+function useDelete(options) {
+  const [state, setState] = useState(INITIAL_STATE5);
+  const contextApi = useContext(S3Context);
+  const optsRef = useLiveRef(options);
+  const apiRef = useLiveRef(contextApi);
+  const pendingKeyRef = useRef(null);
+  const requestDelete = useCallback((key) => {
+    pendingKeyRef.current = key;
+    setState({ phase: "confirming", error: null, pendingKey: key });
+  }, []);
+  const confirmDelete = useCallback(async () => {
+    const key = pendingKeyRef.current;
+    if (!key) return;
+    const opts = optsRef.current;
+    const api = opts.api ?? apiRef.current;
+    if (!api)
+      throw new Error(
+        "[better-s3] No S3Api client found. Pass `api` to useDelete or wrap with <S3Provider>."
+      );
+    if (opts.beforeDelete) {
+      const allowed = await opts.beforeDelete(key);
+      if (!allowed) {
+        setState({
+          phase: "error",
+          error: "Delete blocked by beforeDelete hook",
+          pendingKey: null
+        });
+        opts.onError?.(key, new Error("blocked"), "confirming");
+        pendingKeyRef.current = null;
+        return;
+      }
+    }
+    setState((s) => ({ ...s, phase: "deleting", error: null }));
+    opts.onDeleteStart?.(key);
+    try {
+      await api.delete(key, { bucket: opts.bucket });
+      pendingKeyRef.current = null;
+      setState({ phase: "success", error: null, pendingKey: null });
+      await opts.onSuccess?.(key);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Delete failed";
+      setState((s) => ({ ...s, phase: "error", error: message }));
+      opts.onError?.(key, err, "deleting");
+    }
+  }, []);
+  const cancelDelete = useCallback(() => {
+    pendingKeyRef.current = null;
+    setState(INITIAL_STATE5);
+  }, []);
+  const reset = useCallback(() => {
+    pendingKeyRef.current = null;
+    setState(INITIAL_STATE5);
+  }, []);
+  return {
+    phase: state.phase,
+    error: state.error,
+    pendingKey: state.pendingKey,
+    requestDelete,
+    confirmDelete,
+    cancelDelete,
+    reset
+  };
+}
+
+export { S3Context, S3Provider, S3UploadError, buildObjectKey, createLocalStorageStore, createMemoryStore, createS3Api as createPresignApi, createS3Api, createS3Client, createSpeedTracker, formatEta, formatFileSize, formatSpeed, formatUploadProgress, getFileExtension, parseContentDispositionFilename, truncateFilename, uploadFile, uploadFiles, useDelete, useDownload, useFetchDownload, useMultiUpload, useMultiUploadControls, useS3Client, useUpload, useUploadControls, validateFile };
+//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map