@better-s3/react 3.1045.2 → 3.1046.0

package/dist/types/download.d.ts

@@ -1,2 +1,19 @@
-export type { DownloadPhase, DownloadHooks, UseDownloadState, UseDownloadReturn, } from "../use-download";
-export type { FetchDownloadPhase, FetchDownloadProgress, FetchDownloadHooks, } from "../use-fetch-download";
+import type { UploadProgress } from "./upload";
+export type DownloadPhase = "idle" | "presigning" | "error";
+export type DownloadHooks = {
+    beforeDownload?: (key: string) => Promise<boolean> | boolean;
+    /** Fires as soon as the browser has been handed the URL — not when download completes. */
+    onInitiated?: (key: string) => void;
+    onError?: (key: string, error: unknown) => void;
+};
+export type FetchDownloadPhase = "idle" | "presigning" | "downloading" | "success" | "error";
+/** Identical shape to {@link UploadProgress}. */
+export type FetchDownloadProgress = UploadProgress;
+export type FetchDownloadHooks = {
+    beforeDownload?: (key: string) => Promise<boolean> | boolean;
+    onDownloadStart?: (key: string) => void;
+    onProgress?: (key: string, progress: UploadProgress) => void;
+    onSuccess?: (key: string, fileName: string) => Promise<void> | void;
+    onError?: (key: string, error: unknown, phase: FetchDownloadPhase) => void;
+    onCancel?: (key: string) => void;
+};

package/dist/types/error.d.ts

@@ -0,0 +1,14 @@
+import type { UploadPhase } from "./upload";
+/**
+ * Structured error thrown by the upload engine.
+ *
+ * - `code` — machine-readable error code (e.g. `"VALIDATION_ERROR"`, `"NETWORK_ERROR"`)
+ * - `statusCode` — HTTP status code when the error originated from a server response
+ * - `phase` — upload phase in which the error occurred
+ */
+export declare class S3UploadError extends Error {
+    readonly code: string;
+    readonly statusCode: number | undefined;
+    readonly phase: UploadPhase | undefined;
+    constructor(message: string, code: string, statusCode?: number, phase?: UploadPhase);
+}

package/dist/types/index.d.ts

@@ -1,4 +1,7 @@
+export * from "./s3-api";
 export * from "./upload";
+export * from "./upload-store";
+export * from "./error";
 export * from "./multi-upload";
 export * from "./download";
 export * from "./delete";

package/dist/types/s3-api.d.ts

@@ -0,0 +1,158 @@
+export type PresignResponse = {
+    key: string;
+    bucket: string;
+    url: string;
+    expiresIn: number;
+};
+export type UploadPresignResponse = {
+    key: string;
+    bucket: string;
+    url: string;
+    expiresIn: number;
+    method: "post" | "put";
+    /** Present when `method` is `"post"`. Must be appended to FormData before the file. */
+    fields?: Record<string, string>;
+    /** Present when `method` is `"put"`. Must be set as request headers on the PUT request. */
+    headers?: Record<string, string>;
+};
+/** @deprecated Use {@link UploadPresignResponse} instead. */
+export type PresignedPostResponse = UploadPresignResponse;
+export type MultipartInitResponse = {
+    key: string;
+    bucket: string;
+    uploadId: string;
+};
+export type MultipartPartResponse = {
+    presignedUrl: string;
+    partNumber: number;
+    uploadId: string;
+    bucket: string;
+    expiresIn: number;
+    /** Exact byte size locked into this part's presigned URL signature. */
+    partSize?: number;
+};
+export type MultipartListPartsResponse = {
+    parts: Array<{
+        partNumber: number;
+        /** Byte size of the uploaded part. */
+        size: number;
+        /** ETag of the uploaded part. */
+        eTag: string;
+    }>;
+};
+export type UploadConfirmResponse = {
+    key: string;
+    bucket: string;
+    contentType?: string;
+    contentLength: number;
+    eTag?: string;
+    /** S3 object metadata (x-amz-meta-*). Always present; empty object when no metadata was stored. */
+    metadata: Record<string, string>;
+    /** Resolved ACL. Omitted when ACL lookup is disabled or unsupported. */
+    acl?: "private" | "public-read";
+    /** Display file name parsed from the object's Content-Disposition header. */
+    fileName?: string;
+    /** Object version ID. Only present when bucket versioning is enabled. */
+    versionId?: string;
+    /** Last-modified timestamp from HeadObject (ISO 8601 string). */
+    lastModified?: string;
+};
+/**
+ * Protocol interface for the presign API consumed by `@better-s3/react` hooks.
+ *
+ * The default implementation is `createS3Api()` from `@better-s3/server`, but
+ * any backend that satisfies this interface can be used instead.
+ */
+export type S3Api = {
+    upload: (payload: {
+        key: string;
+        contentType?: string;
+        /**
+         * Exact byte size of the file. When provided the presigned POST policy
+         * locks `content-length-range` to `[fileSize, fileSize]` so S3 rejects
+         * uploads of any other size at the storage layer.
+         */
+        fileSize?: number;
+        metadata?: Record<string, string>;
+        bucket?: string;
+        acl?: "private" | "public-read";
+        /** Original file name. Stored as `Content-Disposition` on the S3 object. */
+        fileName?: string;
+    }) => Promise<UploadPresignResponse>;
+    confirm: (payload: {
+        key: string;
+        bucket?: string;
+    }) => Promise<UploadConfirmResponse>;
+    download: (key: string, options?: {
+        fileName?: string;
+        bucket?: string;
+    }) => Promise<PresignResponse>;
+    delete: (key: string, options?: {
+        bucket?: string;
+    }) => Promise<{
+        success: boolean;
+        bucket: string;
+        key: string;
+    }>;
+    multipart: {
+        init: (payload: {
+            key: string;
+            contentType?: string;
+            /** Declared total byte size of the file. */
+            fileSize?: number;
+            metadata?: Record<string, string>;
+            bucket?: string;
+            acl?: "private" | "public-read";
+            /** Original file name. Stored as `Content-Disposition` on the S3 object. */
+            fileName?: string;
+        }) => Promise<MultipartInitResponse>;
+        signPart: (payload: {
+            key: string;
+            uploadId: string;
+            partNumber: number;
+            /**
+             * Exact byte size of the part. When provided, Content-Length is included
+             * in the HMAC signature so S3 rejects any part body of a different size.
+             */
+            partSize?: number;
+            bucket?: string;
+        }) => Promise<MultipartPartResponse>;
+        /**
+         * List already-uploaded parts for an in-progress multipart upload.
+         * Used by the resumable upload flow to skip already-completed parts.
+         */
+        listParts: (payload: {
+            key: string;
+            uploadId: string;
+            bucket?: string;
+        }) => Promise<MultipartListPartsResponse>;
+        complete: (payload: {
+            key: string;
+            uploadId: string;
+            parts: Array<{
+                partNumber: number;
+            }>;
+            bucket?: string;
+        }) => Promise<{
+            key: string;
+            bucket: string;
+            uploadId: string;
+            contentLength: number;
+            contentType?: string;
+            eTag?: string;
+            /** S3 object metadata (x-amz-meta-*). Always present; empty object when no metadata was stored. */
+            metadata: Record<string, string>;
+            /** Object version ID. Only present when bucket versioning is enabled. */
+            versionId?: string;
+            /** Last-modified timestamp from HeadObject (ISO 8601 string). */
+            lastModified?: string;
+        }>;
+        abort: (payload: {
+            key: string;
+            uploadId: string;
+            bucket?: string;
+        }) => Promise<{
+            aborted: boolean;
+        }>;
+    };
+};

package/dist/types/upload-store.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Minimal state that must be persisted to resume a multipart upload.
+ */
+export type StoredUpload = {
+    /** S3 multipart `UploadId` returned by `CreateMultipartUpload`. */
+    uploadId: string;
+    /** S3 object key. */
+    key: string;
+    /** Total file size in bytes — used to verify the same file is being resumed. */
+    fileSize: number;
+    /** Bucket override, if any. */
+    bucket?: string;
+};
+/**
+ * Storage backend for resumable multipart uploads.
+ *
+ * Implement this interface to persist `uploadId` state in any storage system
+ * (database, Redis, IndexedDB, etc.). The default implementation uses
+ * `localStorage` via `createLocalStorageStore()`.
+ *
+ * @example
+ * ```ts
+ * // Custom database-backed store
+ * const dbStore: UploadStore = {
+ *   async get(key, fileSize) {
+ *     const row = await db.uploads.findFirst({ where: { key, fileSize } });
+ *     return row ? { uploadId: row.uploadId, key, fileSize, bucket: row.bucket } : null;
+ *   },
+ *   async set(upload) {
+ *     await db.uploads.upsert({ where: { key: upload.key }, data: upload });
+ *   },
+ *   async delete(key) {
+ *     await db.uploads.deleteMany({ where: { key } });
+ *   },
+ * };
+ * ```
+ */
+export type UploadStore = {
+    /**
+     * Look up a pending upload by its S3 object key and file size.
+     * Returns `null` if no matching upload is found.
+     */
+    get: (key: string, fileSize: number) => StoredUpload | null | Promise<StoredUpload | null>;
+    /**
+     * Persist a new upload state after `CreateMultipartUpload` succeeds.
+     * Called once per upload, before any parts are sent.
+     */
+    set: (upload: StoredUpload) => void | Promise<void>;
+    /**
+     * Remove the upload state after the upload completes or is explicitly
+     * abandoned. Should be a no-op if the key is not found.
+     */
+    delete: (key: string) => void | Promise<void>;
+};

package/dist/types/upload.d.ts

@@ -1,3 +1,4 @@
+import type { UploadStore } from "./upload-store";
 export type UploadResult = {
     key: string;
     url?: string;
@@ -7,6 +8,8 @@ export type UploadProgress = {
     loaded: number;
     total: number;
     percent: number;
+    /** Instantaneous transfer speed in bytes/second. `undefined` until measurable. */
+    speed?: number;
 };
 export type UploadPhase = "idle" | "validating" | "presigning" | "uploading" | "finalizing" | "success" | "error";
 export type UploadRequestOptions = {
@@ -24,21 +27,74 @@ export type UploadRequestOptions = {
      * Pass `null` to omit Content-Disposition entirely.
      */
     fileName?: string | null;
+    /**
+     * Per-upload multipart part size in bytes. Overrides `UploadConfig.partSize`.
+     * Minimum 5 MB; ignored for non-multipart uploads.
+     */
+    partSize?: number;
 };
 export type UploadHooks = {
+    /** Runs before the upload starts. Return `false` to block it. */
     beforeUpload?: (file: File) => Promise<boolean> | boolean;
+    /** Fires after validation passes and the upload begins. */
     onUploadStart?: (file: File, key: string) => void;
+    /** Fires continuously while bytes are transferred. */
     onProgress?: (file: File, progress: UploadProgress) => void;
+    /**
+     * Fires after each part is successfully uploaded to S3.
+     * Only called during multipart uploads (files above `multipartThreshold`).
+     */
+    onPartUpload?: (file: File, partNumber: number, totalParts: number) => void;
+    /**
+     * Fires once after `CreateMultipartUpload` succeeds.
+     * Only called during multipart uploads.
+     * Receives the S3-assigned `uploadId` — useful for server-side tracking.
+     */
+    onMultipartInit?: (file: File, uploadId: string) => void;
+    /** Fires when the upload finishes successfully. */
     onSuccess?: (file: File, result: UploadResult) => Promise<void> | void;
+    /** Fires when the upload fails with an unrecoverable error. */
     onError?: (file: File | null, error: unknown, phase: UploadPhase) => void;
+    /** Fires when the upload is cancelled via `cancel()`. */
     onCancel?: (file: File | null) => void;
 };
+export type RetryConfig = {
+    /** Maximum number of retry attempts per request. @default 3 */
+    maxRetries?: number;
+    /** Base delay in ms for exponential backoff. @default 1000 */
+    baseDelay?: number;
+};
 export type UploadConfig = {
     multipart?: boolean;
     accept?: string[];
     maxFileSize?: number;
     maxFiles?: number;
     multipartThreshold?: number;
+    /**
+     * Multipart part size in bytes. Minimum 5 MB.
+     * Can be overridden per-upload via `UploadRequestOptions.partSize`.
+     * @default 5 MB
+     */
+    partSize?: number;
     concurrentParts?: number;
     concurrentFiles?: number;
+    /** Retry configuration for failed network requests. */
+    retry?: RetryConfig;
+    /**
+     * Store for resumable multipart uploads.
+     *
+     * - Omit / `undefined` — resumability disabled; abort immediately on cancel or error.
+     * - `false` — same as omitting; abort immediately on cancel or error.
+     * - Custom `UploadStore` — persist `uploadId` across sessions (localStorage, database, IndexedDB, etc.).
+     *
+     * @example
+     * ```ts
+     * // Enable localStorage-based resumability
+     * useUpload({ api, uploadStore: createLocalStorageStore() });
+     *
+     * // Custom backend
+     * useUpload({ api, uploadStore: myDbStore });
+     * ```
+     */
+    uploadStore?: UploadStore | false;
 };

package/dist/upload/constants.d.ts

@@ -2,5 +2,5 @@ export declare const DEFAULT_MULTIPART_THRESHOLD: number;
 export declare const DEFAULT_PART_SIZE: number;
 export declare const MAX_RETRIES = 3;
 export declare const RETRY_BASE_DELAY = 1000;
-export declare const DEFAULT_CONCURRENT_PARTS = 3;
+export declare const DEFAULT_CONCURRENT_PARTS = 2;
 export declare const DEFAULT_CONCURRENT_FILES = 2;

package/dist/upload/multipart.d.ts

@@ -1,3 +1,4 @@
-import type { UploadProgress, UploadRequestOptions } from "../types";
-import type { S3Api } from "@better-s3/server";
-export declare function uploadMultipart(api: S3Api, file: File, objectKey: string, partSize: number, concurrentParts: number, onProgress?: (progress: UploadProgress) => void, signal?: AbortSignal, requestOptions?: UploadRequestOptions): Promise<string | undefined>;
+import type { UploadProgress, UploadRequestOptions, RetryConfig } from "../types";
+import type { S3Api } from "../types/s3-api";
+import type { UploadStore } from "../types/upload-store";
+export declare function uploadMultipart(api: S3Api, file: File, objectKey: string, partSize: number, concurrentParts: number, onProgress?: (progress: UploadProgress) => void, signal?: AbortSignal, requestOptions?: UploadRequestOptions, retryConfig?: RetryConfig, uploadStore?: UploadStore | false, onPartUpload?: (partNumber: number, totalParts: number) => void, onMultipartInit?: (uploadId: string, key: string) => void): Promise<string | undefined>;

package/dist/upload/retry.d.ts

@@ -1 +1,2 @@
-export declare function withRetry<T>(fn: () => Promise<T>, retries: number, signal?: AbortSignal): Promise<T>;
+import type { RetryConfig } from "../types";
+export declare function withRetry<T>(fn: () => Promise<T>, retryConfig: RetryConfig | undefined, signal?: AbortSignal): Promise<T>;

package/dist/upload/upload-file.d.ts

@@ -1,8 +1,12 @@
 import type { UploadConfig, UploadProgress, UploadResult, UploadRequestOptions } from "../types";
-import type { S3Api } from "@better-s3/server";
+import type { S3Api } from "../types/s3-api";
 export type UploadEngineCallbacks = {
     onProgress?: (progress: UploadProgress) => void;
     /** Called when the upload transitions between internal phases. */
     onPhaseChange?: (phase: "presigning" | "uploading" | "finalizing") => void;
+    /** Called after each individual multipart part is successfully uploaded. */
+    onPartUpload?: (partNumber: number, totalParts: number) => void;
+    /** Called once after `CreateMultipartUpload` succeeds with the S3-assigned `uploadId` and final object `key`. */
+    onMultipartInit?: (uploadId: string, key: string) => void;
 };
 export declare function uploadFile(api: S3Api, file: File, objectKey: string, config?: UploadConfig, callbacks?: UploadEngineCallbacks, signal?: AbortSignal, requestOptions?: UploadRequestOptions): Promise<UploadResult>;

package/dist/upload/upload-files.d.ts

@@ -1,5 +1,5 @@
 import type { UploadConfig, UploadProgress, UploadResult, UploadRequestOptions } from "../types";
-import type { S3Api } from "@better-s3/server";
+import type { S3Api } from "../types/s3-api";
 export type FileItemStatus = "pending" | "uploading" | "success" | "error";
 export type FileItem = {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-s3/react",
-  "version": "3.1045.2",
+  "version": "3.1046.0",
   "description": "React hooks for S3-compatible file uploads, downloads, and deletes",
   "keywords": [
     "s3",
@@ -32,9 +32,6 @@
   "files": [
     "dist"
   ],
-  "dependencies": {
-    "@better-s3/server": "3.1045.2"
-  },
   "peerDependencies": {
     "react": ">=18"
   },

package/dist/helpers.d.ts

@@ -1,7 +0,0 @@
-/**
- * Parses the filename from a `Content-Disposition` header value.
- * Prefers `filename*` (RFC 5987, full Unicode) over `filename`.
- * Returns `fallback` if no filename is found.
- */
-export declare function parseContentDispositionFilename(header: string | null, fallback: string): string;
-export declare function formatFileSize(bytes: number): string;

package/dist/use-fetch-download.d.ts

@@ -1,33 +0,0 @@
-import type { S3Api } from "@better-s3/server";
-export type FetchDownloadPhase = "idle" | "presigning" | "downloading" | "success" | "error";
-export type FetchDownloadProgress = {
-    loaded: number;
-    total: number;
-    percent: number;
-};
-export type FetchDownloadHooks = {
-    beforeDownload?: (key: string) => Promise<boolean> | boolean;
-    onDownloadStart?: (key: string) => void;
-    onProgress?: (key: string, progress: FetchDownloadProgress) => void;
-    onSuccess?: (key: string, fileName: string) => Promise<void> | void;
-    onError?: (key: string, error: unknown, phase: FetchDownloadPhase) => void;
-    onCancel?: (key: string) => void;
-};
-export type UseFetchDownloadOptions = FetchDownloadHooks & {
-    api: S3Api;
-    /** Target bucket (overrides server default) */
-    bucket?: string;
-};
-export type UseFetchDownloadState = {
-    phase: FetchDownloadPhase;
-    progress: FetchDownloadProgress;
-    error: string | null;
-    fileName: string | null;
-    fileSize: number | null;
-};
-export type UseFetchDownloadReturn = UseFetchDownloadState & {
-    download: (key: string, downloadName?: string) => Promise<void>;
-    cancel: () => void;
-    reset: () => void;
-};
-export declare function useFetchDownload(options: UseFetchDownloadOptions): UseFetchDownloadReturn;

package/dist/use-upload-controls.d.ts

@@ -1,63 +0,0 @@
-import type { UploadPhase, UploadProgress, UploadResult, UploadRequestOptions, MultiUploadFileState, MultiUploadPhase } from "./types";
-import type { S3Api } from "@better-s3/server";
-import type { UploadConfig } from "./types";
-export type UseUploadControlsOptions = UploadConfig & {
-    api: S3Api;
-    objectKey: string | ((file: File) => string);
-    /**
-     * Maximum number of files. When > 1 the hook switches to multi-upload mode
-     * and the native file picker allows selecting multiple files.
-     * @default 1
-     */
-    maxFiles?: number;
-    /** Static request options applied to all files (multi mode) */
-    uploadOptions?: UploadRequestOptions;
-    /** Per-file request options */
-    getUploadOptions?: (file: File) => UploadRequestOptions;
-    beforeUpload?: ((file: File) => boolean | Promise<boolean>) | ((files: File[]) => boolean | Promise<boolean>);
-    onUploadStart?: ((file: File, key: string) => void) | ((files: File[]) => void);
-    onProgress?: ((file: File, progress: UploadProgress) => void) | ((progress: UploadProgress) => void);
-    onSuccess?: ((file: File, result: UploadResult) => void | Promise<void>) | ((results: UploadResult[]) => void | Promise<void>);
-    onError?: ((file: File | null, error: unknown, phase: UploadPhase) => void) | ((error: unknown) => void);
-    onCancel?: ((file: File | null) => void) | (() => void);
-    onFileProgress?: (file: File, progress: UploadProgress) => void;
-    onFileSuccess?: (file: File, result: UploadResult) => void;
-    onFileError?: (file: File, error: string) => void;
-};
-export type UseUploadControlsReturn = {
-    /** Whether the hook is in single-file or multi-file mode */
-    mode: "single" | "multi";
-    phase: UploadPhase | MultiUploadPhase;
-    /** Info about the selected file (single mode only) */
-    fileInfo: {
-        name: string;
-        size: number;
-    } | null;
-    /** Upload progress (single mode) */
-    progress: UploadProgress;
-    /** Per-file states (multi mode only) */
-    files: MultiUploadFileState[];
-    /** Aggregated progress across all files (multi mode) */
-    totalProgress: UploadProgress;
-    error: string | null;
-    isUploading: boolean;
-    handleFiles: (files: FileList | null) => void;
-    openFilePicker: () => void;
-    cancel: () => void;
-    reset: () => void;
-    /** Spread on a hidden `<input>` element */
-    inputProps: {
-        ref: React.RefObject<HTMLInputElement | null>;
-        type: "file";
-        multiple?: true;
-        accept?: string;
-        hidden: true;
-        onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
-    };
-    /** Spread on a container to enable drag-and-drop */
-    dropHandlers: {
-        onDragOver: (e: React.DragEvent) => void;
-        onDrop: (e: React.DragEvent) => void;
-    };
-};
-export declare function useUploadControls(options: UseUploadControlsOptions): UseUploadControlsReturn;

package/dist/use-upload.d.ts

@@ -1,19 +0,0 @@
-import type { S3Api } from "@better-s3/server";
-import type { UploadConfig, UploadHooks, UploadPhase, UploadProgress, UploadResult, UploadRequestOptions } from "./types";
-export type UseUploadOptions = UploadConfig & UploadHooks & {
-    api: S3Api;
-};
-export type UseUploadState = {
-    phase: UploadPhase;
-    progress: UploadProgress;
-    error: string | null;
-    result: UploadResult | null;
-    fileName: string | null;
-    fileSize: number | null;
-};
-export type UseUploadReturn = UseUploadState & {
-    upload: (file: File, objectKey: string, requestOptions?: UploadRequestOptions) => Promise<void>;
-    cancel: () => void;
-    reset: () => void;
-};
-export declare function useUpload(options: UseUploadOptions): UseUploadReturn;