@better-s3/react 3.1045.2 → 3.1047.0

package/dist/api.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Client-side factory for the better-s3 presign API.
+ *
+ * Accepts an `S3Api` object — implement each method to call your own backend
+ * endpoint, tRPC mutation, GraphQL query, or anything else. The object is
+ * returned as-is; `createS3Client` just enforces the type contract.
+ *
+ * If you are using `@better-s3/server`, use `createS3Api` from that package
+ * instead — it builds a standard fetch client from a base path.
+ *
+ * @example
+ * ```ts
+ * import { createS3Client } from "@better-s3/react";
+ *
+ * export const s3Client = createS3Client({
+ *   async upload(payload) {
+ *     return fetch("/api/storage/presign", { method: "POST", body: JSON.stringify(payload) })
+ *       .then(r => r.json());
+ *   },
+ *   async confirm(payload) { ... },
+ *   async download(key, options) { ... },
+ *   async delete(key) { ... },
+ *   multipart: { init, signPart, listParts, complete, abort },
+ * });
+ * ```
+ */
+import type { S3Api } from "./types/s3-api";
+export declare function createS3Client(input: S3Api): S3Api;
+/** @deprecated Use {@link createS3Client} instead. */
+export declare const createS3Api: typeof createS3Client;

package/dist/helpers/build-object-key.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Builds an S3 object key by joining path segments with `/`.
+ *
+ * Trims leading/trailing slashes from each segment and removes empty ones,
+ * so you can safely pass optional parts without worrying about double-slashes.
+ *
+ * Follows the recommended better-s3 key convention:
+ * - Personal mode: `buildObjectKey(userId, `${nanoid()}.${ext}`)` → `"user_123/abc.png"`
+ * - Org mode: `buildObjectKey(orgId, userId, `${nanoid()}.${ext}`)` → `"org_1/user_123/abc.png"`
+ *
+ * @example
+ * ```ts
+ * buildObjectKey("user_123", "uploads", "photo.png")
+ * // → "user_123/uploads/photo.png"
+ *
+ * buildObjectKey("org_1", "", "user_123", "doc.pdf")
+ * // → "org_1/user_123/doc.pdf"
+ * ```
+ */
+export declare function buildObjectKey(...parts: string[]): string;

package/dist/helpers/format-eta.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Formats an estimated remaining time given the remaining bytes and current speed.
+ *
+ * Returns `null` when speed is 0 or nothing remains (not yet calculable).
+ *
+ * @example
+ * formatEta(4_400_000, 450_000)    // → "9s"
+ * formatEta(4_400_000, 75_000)     // → "58s"
+ * formatEta(90_000_000, 1_500_000) // → "1m"
+ * formatEta(5_400_000_000, 500_000) // → "3h"
+ */
+export declare function formatEta(remainingBytes: number, bytesPerSecond: number): string | null;

package/dist/helpers/format-file-size.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Formats a byte count into a human-readable string.
+ *
+ * @example
+ * ```ts
+ * formatFileSize(0)          // "0 B"
+ * formatFileSize(1500)       // "1.5 KB"
+ * formatFileSize(1048576)    // "1.0 MB"
+ * ```
+ */
+export declare function formatFileSize(bytes: number): string;

package/dist/helpers/format-speed.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Formats a transfer speed (bytes/second) as a human-readable string.
+ *
+ * @example
+ * formatSpeed(1_200_000) // → "1.2 MB/s"
+ * formatSpeed(512)       // → "512 B/s"
+ */
+export declare function formatSpeed(bytesPerSecond: number): string;

package/dist/helpers/format-upload-progress.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Formats upload progress as a human-readable transfer string.
+ *
+ * @param loaded   Bytes transferred so far.
+ * @param total    Total bytes to transfer (0 means unknown).
+ * @param percent  Transfer percentage (0–100).
+ *
+ * @example
+ * ```ts
+ * formatUploadProgress(1_200_000, 5_600_000, 21)
+ * // → "1.2 MB / 5.6 MB (21%)"
+ *
+ * formatUploadProgress(1_200_000, 0, 0)
+ * // → "1.2 MB"
+ * ```
+ */
+export declare function formatUploadProgress(loaded: number, total: number, percent: number): string;

package/dist/helpers/get-file-extension.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Extracts the lowercase file extension (without the dot) from a filename.
+ *
+ * Returns an empty string when the filename has no extension.
+ *
+ * @example
+ * ```ts
+ * getFileExtension("photo.JPG")    // "jpg"
+ * getFileExtension("archive.tar.gz") // "gz"
+ * getFileExtension("README")       // ""
+ * ```
+ */
+export declare function getFileExtension(filename: string): string;

package/dist/helpers/index.d.ts

@@ -0,0 +1,10 @@
+export { formatFileSize } from "./format-file-size";
+export { validateFile } from "./validate-file";
+export { parseContentDispositionFilename } from "./parse-content-disposition";
+export { formatUploadProgress } from "./format-upload-progress";
+export { formatSpeed } from "./format-speed";
+export { formatEta } from "./format-eta";
+export { buildObjectKey } from "./build-object-key";
+export { getFileExtension } from "./get-file-extension";
+export { truncateFilename } from "./truncate-filename";
+export { createSpeedTracker, type SpeedTracker } from "./speed-tracker";

package/dist/helpers/parse-content-disposition.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Extracts a display filename from a `Content-Disposition` response header.
+ *
+ * Prefers the RFC 5987 `filename*=UTF-8''…` encoding (full Unicode support)
+ * over the plain ASCII `filename="…"` fallback.
+ *
+ * @param header   The raw `Content-Disposition` header value (or `null`).
+ * @param fallback Returned when no filename can be extracted.
+ *
+ * @example
+ * ```ts
+ * const name = parseContentDispositionFilename(
+ *   response.headers.get("content-disposition"),
+ *   "download",
+ * );
+ * ```
+ */
+export declare function parseContentDispositionFilename(header: string | null, fallback: string): string;

package/dist/helpers/speed-tracker.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Creates a sliding-window transfer speed calculator.
+ *
+ * Tracks bytes transferred over a rolling time window to produce a smooth,
+ * instantaneous speed reading in bytes/second.
+ *
+ * @param windowMs  Rolling window duration in milliseconds. @default 3000
+ */
+export declare function createSpeedTracker(windowMs?: number): {
+    /**
+     * Record the latest cumulative `loaded` byte count.
+     * Returns the current speed in bytes/second (0 until at least 2 samples exist).
+     */
+    update(loaded: number): number;
+    reset(): void;
+};
+export type SpeedTracker = ReturnType<typeof createSpeedTracker>;

package/dist/helpers/truncate-filename.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Truncates a filename while always preserving the file extension.
+ * The cut happens before the extension so the extension is always visible.
+ *
+ * truncateFilename("namenamenamenamename.pdf", 20) → "namenamename… .pdf"
+ * truncateFilename("short.pdf", 20)               → "short.pdf"
+ * truncateFilename(".gitignore", 8)               → ".gitigno…"
+ */
+export declare function truncateFilename(name: string, maxChars?: number): string;

package/dist/helpers/validate-file.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Validates a `File` against accept-list and size constraints.
+ *
+ * Returns a human-readable error string when validation fails,
+ * or `null` when the file is valid.
+ *
+ * Mirrors the server-side `validateFile` so you can apply the same
+ * rules on the client before initiating an upload.
+ *
+ * @example
+ * ```ts
+ * const error = validateFile(file, {
+ *   accept: ["image/*", ".pdf"],
+ *   maxFileSize: 10 * 1024 * 1024, // 10 MB
+ * });
+ * if (error) toast.error(error);
+ * ```
+ */
+export declare function validateFile(file: File, options: {
+    accept?: string[];
+    maxFileSize?: number;
+}): string | null;

package/dist/hooks/index.d.ts

@@ -0,0 +1,7 @@
+export { useUpload, type UseUploadOptions, type UseUploadState, type UseUploadReturn, } from "./use-upload";
+export { useMultiUpload, type UseMultiUploadOptions, type UseMultiUploadState, type UseMultiUploadReturn, } from "./use-multi-upload";
+export { useUploadControls, type UseUploadControlsOptions, type UseUploadControlsReturn, } from "./use-upload-controls";
+export { useMultiUploadControls, type UseMultiUploadControlsOptions, type UseMultiUploadControlsReturn, } from "./use-multi-upload-controls";
+export { useDownload, type DownloadPhase, type DownloadHooks, type UseDownloadOptions, type UseDownloadState, type UseDownloadReturn, } from "./use-download";
+export { useFetchDownload, type FetchDownloadPhase, type FetchDownloadProgress, type FetchDownloadHooks, type UseFetchDownloadOptions, type UseFetchDownloadState, type UseFetchDownloadReturn, } from "./use-fetch-download";
+export { useDelete, type UseDeleteOptions, type UseDeleteState, type UseDeleteReturn, } from "./use-delete";

package/dist/{use-delete.d.ts → hooks/use-delete.d.ts}

@@ -1,7 +1,8 @@
-import type { S3Api } from "@better-s3/server";
-import type { DeletePhase, DeleteHooks } from "./types";
+import type { S3Api } from "../types/s3-api";
+import type { DeletePhase, DeleteHooks } from "../types";
 export type UseDeleteOptions = DeleteHooks & {
-    api: S3Api;
+    /** S3Api client. Optional when an `<S3Provider>` is present in the tree. */
+    api?: S3Api;
     /** Target bucket (overrides server default) */
     bucket?: string;
 };

package/dist/{use-download.d.ts → hooks/use-download.d.ts}

@@ -1,14 +1,9 @@
-import type { S3Api } from "@better-s3/server";
-/** "presigning" = fetching the presigned URL from the server; download itself is native */
-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;
-};
+import type { S3Api } from "../types/s3-api";
+export type { DownloadPhase, DownloadHooks } from "../types/download";
+import type { DownloadPhase, DownloadHooks } from "../types/download";
 export type UseDownloadOptions = DownloadHooks & {
-    api: S3Api;
+    /** S3Api client. Optional when an `<S3Provider>` is present in the tree. */
+    api?: S3Api;
     /** Target bucket (overrides server default) */
     bucket?: string;
 };

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

@@ -0,0 +1,23 @@
+import type { S3Api } from "../types/s3-api";
+import type { FetchDownloadPhase, FetchDownloadHooks } from "../types/download";
+import type { UploadProgress } from "../types/upload";
+export type { FetchDownloadPhase, FetchDownloadProgress, FetchDownloadHooks, } from "../types/download";
+export type UseFetchDownloadOptions = FetchDownloadHooks & {
+    /** S3Api client. Optional when an `<S3Provider>` is present in the tree. */
+    api?: S3Api;
+    /** Target bucket (overrides server default) */
+    bucket?: string;
+};
+export type UseFetchDownloadState = {
+    phase: FetchDownloadPhase;
+    progress: UploadProgress;
+    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/hooks/use-multi-upload-controls.d.ts

@@ -0,0 +1,33 @@
+import type { UploadProgress, MultiUploadFileState, MultiUploadPhase } from "../types";
+import { type UseMultiUploadOptions } from "./use-multi-upload";
+export type UseMultiUploadControlsOptions = UseMultiUploadOptions & {
+    objectKey: string | ((file: File) => string);
+};
+export type UseMultiUploadControlsReturn = {
+    phase: MultiUploadPhase;
+    /** Per-file upload states. */
+    files: MultiUploadFileState[];
+    /** Aggregated progress across all files. */
+    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 useMultiUploadControls(options: UseMultiUploadControlsOptions): UseMultiUploadControlsReturn;

package/dist/{use-multi-upload.d.ts → hooks/use-multi-upload.d.ts}

@@ -1,7 +1,8 @@
-import type { S3Api } from "@better-s3/server";
-import type { UploadConfig, UploadProgress, UploadRequestOptions, MultiUploadPhase, MultiUploadFileState, MultiUploadHooks } from "./types";
+import type { S3Api } from "../types/s3-api";
+import type { UploadConfig, UploadProgress, UploadRequestOptions, MultiUploadPhase, MultiUploadFileState, MultiUploadHooks } from "../types";
 export type UseMultiUploadOptions = UploadConfig & MultiUploadHooks & {
-    api: S3Api;
+    /** S3Api client. Optional when an `<S3Provider>` is present in the tree. */
+    api?: S3Api;
     /** Static request options applied to all files */
     uploadOptions?: UploadRequestOptions;
     /** Per-file request options (overrides uploadOptions) */

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

@@ -0,0 +1,44 @@
+import type { UploadPhase, UploadProgress, UploadRequestOptions } from "../types";
+import { type UseUploadOptions } from "./use-upload";
+export type UseUploadControlsOptions = UseUploadOptions & {
+    objectKey: string | ((file: File) => string);
+    /** Static request options applied to the upload. */
+    uploadOptions?: UploadRequestOptions;
+    /** Per-upload request options override. */
+    getUploadOptions?: (file: File) => UploadRequestOptions;
+};
+export type UseUploadControlsReturn = {
+    phase: UploadPhase;
+    /** Info about the selected file. */
+    fileInfo: {
+        name: string;
+        size: number;
+    } | null;
+    progress: UploadProgress;
+    error: string | null;
+    isUploading: boolean;
+    handleFiles: (files: FileList | null) => void;
+    openFilePicker: () => void;
+    cancel: () => void;
+    /**
+     * Soft-stop: preserves S3 parts and store entry so a future `upload()` can
+     * resume. For non-resumable uploads, identical to `cancel()`.
+     * See `UseUploadReturn.detach` for full semantics.
+     */
+    detach: () => void;
+    reset: () => void;
+    /** Spread on a hidden `<input>` element. */
+    inputProps: {
+        ref: React.RefObject<HTMLInputElement | null>;
+        type: "file";
+        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/hooks/use-upload.d.ts

@@ -0,0 +1,75 @@
+import type { S3Api } from "../types/s3-api";
+import type { UploadConfig, UploadHooks, UploadPhase, UploadProgress, UploadResult, UploadRequestOptions } from "../types";
+export type UseUploadOptions = UploadConfig & UploadHooks & {
+    /** S3Api client. Optional when an `<S3Provider>` is present in the tree. */
+    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 & {
+    /**
+     * Start an upload.
+     *
+     * Safe to call again after `success`, `error`, or `cancel` — state is reset
+     * automatically before the new upload begins.
+     *
+     * If `uploadStore` is configured and a previous upload for the same
+     * `objectKey` was interrupted (e.g. via `detach()`), the engine will find
+     * the stored `uploadId`, call `listParts`, and resume from the last completed
+     * part rather than starting a new multipart upload.
+     */
+    upload: (file: File, objectKey: string, requestOptions?: UploadRequestOptions) => Promise<void>;
+    /**
+     * Abort the upload and fully clean up all resources.
+     *
+     * - Stops the in-flight network request immediately.
+     * - For multipart uploads: calls `AbortMultipartUpload` on S3 so incomplete
+     *   parts are freed right away (instead of waiting for the bucket lifecycle
+     *   policy to expire them).
+     * - Removes the `uploadStore` entry if one was provided.
+     * - Resets state to `idle`.
+     *
+     * Use this for a "Cancel" button that the user explicitly clicks to abandon
+     * the upload entirely.
+     */
+    cancel: () => void;
+    /**
+     * Stop the upload and — when multipart with `uploadStore` is active —
+     * preserve S3 parts and the store entry for a future resume.
+     *
+     * Compared to `cancel()`:
+     * - Does **not** call `AbortMultipartUpload` (parts stay on S3).
+     * - Does **not** remove the `uploadStore` entry.
+     * - Does **not** fire the `onCancel` callback.
+     *
+     * The next call to `upload(sameFile, sameKey)` will detect the stored
+     * `uploadId`, verify the existing parts via `listParts`, and continue
+     * uploading from where it stopped.
+     *
+     * For **simple uploads** or multipart **without** `uploadStore`, this is
+     * identical to `cancel()` — there is no S3 state worth preserving.
+     *
+     * Intended for custom UIs that want to offer a "save for later / resume"
+     * workflow. The built-in UI components always use `cancel()`.
+     */
+    detach: () => void;
+    /**
+     * Reset UI state to `idle` without touching any S3 or store resources.
+     *
+     * - Stops the in-flight network request if one is active.
+     * - Does **not** call `AbortMultipartUpload`.
+     * - Does **not** modify `uploadStore`.
+     * - Does **not** fire `onCancel`.
+     *
+     * Use this to clear an error or success state from the UI, or when you
+     * handle cleanup yourself outside this hook.
+     */
+    reset: () => void;
+};
+export declare function useUpload(options: UseUploadOptions): UseUploadReturn;

package/dist/index.d.ts

@@ -1,10 +1,15 @@
 export * from "./types";
-export { formatFileSize } from "./helpers";
+export { createS3Client, createS3Api } from "./api";
+/** @deprecated Use {@link createS3Client} instead. */
+export { createS3Api as createPresignApi } from "./api";
+export { S3Provider, useS3Client, S3Context } from "./s3-provider";
+export { createLocalStorageStore, createMemoryStore } from "./store";
 export { uploadFile, uploadFiles, type UploadEngineCallbacks, type FileItem, type FileItemStatus, type MultiUploadCallbacks, } from "./upload";
-export { createS3Api, createS3Api as createPresignApi, validateFile, type S3Api, type S3Api as PresignApi, type PresignResponse, type PresignedPostResponse, type MultipartInitResponse, type MultipartPartResponse, type UploadConfirmResponse, } from "@better-s3/server";
-export { useUpload, type UseUploadOptions, type UseUploadState, type UseUploadReturn, } from "./use-upload";
-export { useMultiUpload, type UseMultiUploadOptions, type UseMultiUploadState, type UseMultiUploadReturn, } from "./use-multi-upload";
-export { useUploadControls, type UseUploadControlsOptions, type UseUploadControlsReturn, } from "./use-upload-controls";
-export { useDownload, type DownloadPhase, type DownloadHooks, type UseDownloadOptions, type UseDownloadState, type UseDownloadReturn, } from "./use-download";
-export { useFetchDownload, type FetchDownloadPhase, type FetchDownloadProgress, type FetchDownloadHooks, type UseFetchDownloadOptions, type UseFetchDownloadState, type UseFetchDownloadReturn, } from "./use-fetch-download";
-export { useDelete, type UseDeleteOptions, type UseDeleteState, type UseDeleteReturn, } from "./use-delete";
+export { formatFileSize, validateFile, parseContentDispositionFilename, formatUploadProgress, formatSpeed, formatEta, buildObjectKey, getFileExtension, truncateFilename, createSpeedTracker, type SpeedTracker, } from "./helpers";
+export { useUpload, type UseUploadOptions, type UseUploadState, type UseUploadReturn, } from "./hooks/use-upload";
+export { useMultiUpload, type UseMultiUploadOptions, type UseMultiUploadState, type UseMultiUploadReturn, } from "./hooks/use-multi-upload";
+export { useUploadControls, type UseUploadControlsOptions, type UseUploadControlsReturn, } from "./hooks/use-upload-controls";
+export { useMultiUploadControls, type UseMultiUploadControlsOptions, type UseMultiUploadControlsReturn, } from "./hooks/use-multi-upload-controls";
+export { useDownload, type DownloadPhase, type DownloadHooks, type UseDownloadOptions, type UseDownloadState, type UseDownloadReturn, } from "./hooks/use-download";
+export { useFetchDownload, type FetchDownloadPhase, type FetchDownloadProgress, type FetchDownloadHooks, type UseFetchDownloadOptions, type UseFetchDownloadState, type UseFetchDownloadReturn, } from "./hooks/use-fetch-download";
+export { useDelete, type UseDeleteOptions, type UseDeleteState, type UseDeleteReturn, } from "./hooks/use-delete";