@better-s3/react 3.1048.0 → 3.1049.0

package/README.md

@@ -1,6 +1,6 @@
 # @better-s3/react
 
-Headless React hooks for S3 file uploads, downloads, and deletes — state management, progress tracking, and cancellation built in.
+Headless React hooks for S3 upload, download, and delete — state, progress, and cancellation built in.
 
 Requires [`@better-s3/server`](../better-s3-server) on the backend. For ready-made components, see [`@better-s3/ui`](../better-s3-ui).
 
@@ -13,85 +13,65 @@ pnpm add @better-s3/react @better-s3/server
 ## Setup
 
 ```ts
-import { createS3Api } from "@better-s3/server";
+import { createS3Api } from "@better-s3/core";
 
 const api = createS3Api();
 ```
 
 ## Hooks
 
-### `useUpload` — Single file upload
+| Hook                     | Use case                                |
+| ------------------------ | --------------------------------------- |
+| `useUploadControls`      | Single file — picker + drag-and-drop    |
+| `useMultiUploadControls` | Multiple files — picker + drag-and-drop |
+| `useUpload`              | Single file — call `upload()` yourself  |
+| `useMultiUpload`         | Batch — call `upload()` yourself        |
+| `useDownload`            | Presigned URL → native browser download |
+| `useFetchDownload`       | Fetch with progress and cancel          |
+| `useDelete`              | Two-step delete with confirmation       |
 
-```tsx
-const { phase, progress, error, upload, cancel, reset } = useUpload({
-  api,
-  accept: ["image/*", ".pdf"],
-  maxFileSize: 10 * 1024 * 1024, // client-side pre-validation (UX)
-  onSuccess: (_file, result) => console.log("Uploaded:", result.key),
-  onError: (_file, error) => {
-    // error.message for size violations:
-    //   Simple:    S3 returns 403 — "Upload failed: 403 Forbidden"
-    //   Multipart: server returns 422 — "File size (X bytes) exceeds …"
-  },
-});
-
-await upload(file, `uploads/${file.name}`, { metadata: { source: "web" } });
-```
-
-**Phases:** `idle → validating → uploading → success | error`
-
-> `maxFileSize` performs a client-side check before the upload starts (good UX). The real enforcement is server-side:
->
-> - **Simple uploads** — S3 enforces exact file size via a signed `content-length-range` policy. The client cannot upload a different-sized file with that URL.
-> - **Multipart uploads** — Server verifies via `HeadObject` after `CompleteMultipartUpload` and deletes the object if the limit is exceeded.
-
-### `useUploadControls` — Upload with file picker & drag-drop
+### Upload — single file
 
 ```tsx
-const { mode, phase, progress, openFilePicker, inputProps, dropHandlers } =
+const { openFilePicker, inputProps, dropHandlers, progress, isUploading } =
   useUploadControls({
     api,
     objectKey: (file) => `uploads/${file.name}`,
-    maxFiles: 5, // > 1 → switches to multi-upload mode automatically
+    accept: ["image/*"],
+    maxFileSize: 10 * 1024 * 1024,
   });
+
+// <input {...inputProps} />
+// <div {...dropHandlers} onClick={openFilePicker}>…</div>
 ```
 
-### `useMultiUpload` — Batch upload
+### Upload — multiple files
 
 ```tsx
-const { phase, files, totalProgress, upload, cancel } = useMultiUpload({
-  api,
-  maxFiles: 10,
-  concurrentFiles: 3,
-});
-
-await upload(selectedFiles, (file) => `uploads/${file.name}`);
+const { openFilePicker, inputProps, files, totalProgress } =
+  useMultiUploadControls({
+    api,
+    objectKey: (file) => `uploads/${file.name}`,
+    maxFiles: 5,
+    concurrentFiles: 3,
+  });
 ```
 
-### `useDownload` — File download
+### Download
 
 ```tsx
-const { phase, error, download, reset } = useDownload({ api });
+const { download } = useDownload({ api });
 download("uploads/photo.jpg", "photo.jpg");
 ```
 
-### `useDelete` — File deletion with confirmation
+### Delete
 
 ```tsx
-const { phase, pendingKey, requestDelete, confirmDelete, cancelDelete } =
-  useDelete({ api });
-
-requestDelete("uploads/photo.jpg"); // phase → "confirming"
-confirmDelete(); // phase → "deleting" → "success"
+const { requestDelete, confirmDelete } = useDelete({ api });
+requestDelete("uploads/photo.jpg");
+await confirmDelete();
 ```
 
-## Upload modes
-
-| Mode      | When used                                        | Size enforcement                                          |
-| --------- | ------------------------------------------------ | --------------------------------------------------------- |
-| Simple    | `file.size < multipartThreshold` (default 50 MB) | S3 presigned POST policy — exact `content-length-range`   |
-| Multipart | `multipart: true` or file ≥ threshold            | Server `HeadObject` check after `CompleteMultipartUpload` |
-
 ## License
 
 MIT

package/dist/api.d.ts

@@ -5,8 +5,8 @@
  * 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.
+ * If you are using the default better-s3 route layout, use `createS3Api` from
+ * `@better-s3/core` — it builds a standard fetch client from a base path.
  *
  * @example
  * ```ts
@@ -24,7 +24,5 @@
  * });
  * ```
  */
-import type { S3Api } from "./types/s3-api";
+import type { S3Api } from "@better-s3/core";
 export declare function createS3Client(input: S3Api): S3Api;
-/** @deprecated Use {@link createS3Client} instead. */
-export declare const createS3Api: typeof createS3Client;

package/dist/helpers/index.d.ts

@@ -1,10 +1,4 @@
-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/hooks/use-delete.d.ts

@@ -1,20 +1,28 @@
-import type { S3Api } from "../types/s3-api";
+import type { S3Api } from "@better-s3/core";
 import type { DeletePhase, DeleteHooks } from "../types";
+/** Options for {@link useDelete}. */
 export type UseDeleteOptions = DeleteHooks & {
     /** S3Api client. Optional when an `<S3Provider>` is present in the tree. */
     api?: S3Api;
-    /** Target bucket (overrides server default) */
+    /** Target bucket (overrides server default). */
     bucket?: string;
 };
 export type UseDeleteState = {
+    /** Current delete phase. */
     phase: DeletePhase;
+    /** Error message, or `null`. */
     error: string | null;
 };
 export type UseDeleteReturn = UseDeleteState & {
+    /** Key awaiting confirmation, or `null`. */
+    pendingKey: string | null;
+    /** Move to the `confirming` phase for the given key. */
     requestDelete: (key: string) => void;
+    /** Send the delete request for the pending key. */
     confirmDelete: () => Promise<void>;
+    /** Cancel confirmation and return to `idle`. */
     cancelDelete: () => void;
+    /** Reset state to `idle`. */
     reset: () => void;
-    pendingKey: string | null;
 };
 export declare function useDelete(options: UseDeleteOptions): UseDeleteReturn;

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

@@ -1,27 +1,32 @@
-import type { S3Api } from "../types/s3-api";
+import type { S3Api } from "@better-s3/core";
 export type { DownloadPhase, DownloadHooks } from "../types/download";
 import type { DownloadPhase, DownloadHooks } from "../types/download";
+/** Options for {@link useDownload}. */
 export type UseDownloadOptions = DownloadHooks & {
     /** S3Api client. Optional when an `<S3Provider>` is present in the tree. */
     api?: S3Api;
-    /** Target bucket (overrides server default) */
+    /** Target bucket (overrides server default). */
     bucket?: string;
 };
 export type UseDownloadState = {
+    /** Current download phase. */
     phase: DownloadPhase;
+    /** Error message, or `null`. */
     error: string | null;
-    /** Presigned URL — set after a successful presign, cleared on reset */
+    /** Presigned URL — set after a successful presign, cleared on reset. */
     url: string | null;
-    /** Validity window in seconds for the presigned URL */
+    /** Validity window in seconds for the presigned URL. */
     expiresIn: number | null;
 };
 export type UseDownloadReturn = UseDownloadState & {
+    /** Presign and trigger a native browser download. */
     download: (key: string, downloadName?: string) => Promise<void>;
-    /** Fetch the presigned URL without triggering a browser download — for headless use */
+    /** Fetch the presigned URL without triggering a browser download. */
     presign: (key: string, downloadName?: string) => Promise<{
         url: string;
         expiresIn: number;
     } | null>;
+    /** Reset state to `idle`. */
     reset: () => void;
 };
 export declare function useDownload(options: UseDownloadOptions): UseDownloadReturn;

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

@@ -1,23 +1,32 @@
-import type { S3Api } from "../types/s3-api";
+import type { S3Api } from "@better-s3/core";
 import type { FetchDownloadPhase, FetchDownloadHooks } from "../types/download";
 import type { UploadProgress } from "../types/upload";
 export type { FetchDownloadPhase, FetchDownloadProgress, FetchDownloadHooks, } from "../types/download";
+/** Options for {@link useFetchDownload}. */
 export type UseFetchDownloadOptions = FetchDownloadHooks & {
     /** S3Api client. Optional when an `<S3Provider>` is present in the tree. */
     api?: S3Api;
-    /** Target bucket (overrides server default) */
+    /** Target bucket (overrides server default). */
     bucket?: string;
 };
 export type UseFetchDownloadState = {
+    /** Current download phase. */
     phase: FetchDownloadPhase;
+    /** Byte transfer progress. */
     progress: UploadProgress;
+    /** Error message, or `null`. */
     error: string | null;
+    /** Resolved download filename. */
     fileName: string | null;
+    /** Total file size in bytes. */
     fileSize: number | null;
 };
 export type UseFetchDownloadReturn = UseFetchDownloadState & {
+    /** Presign, fetch bytes, and save via the browser. */
     download: (key: string, downloadName?: string) => Promise<void>;
+    /** Abort the active download. */
     cancel: () => void;
+    /** Reset state to `idle`. */
     reset: () => void;
 };
 export declare function useFetchDownload(options: UseFetchDownloadOptions): UseFetchDownloadReturn;

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

@@ -1,19 +1,28 @@
 import type { UploadProgress, MultiUploadFileState, MultiUploadPhase } from "../types";
 import { type UseMultiUploadOptions } from "./use-multi-upload";
+/** Options for {@link useMultiUploadControls}. */
 export type UseMultiUploadControlsOptions = UseMultiUploadOptions & {
+    /** S3 object key, or a function that derives it from each file. */
     objectKey: string | ((file: File) => string);
 };
 export type UseMultiUploadControlsReturn = {
+    /** Current batch upload phase. */
     phase: MultiUploadPhase;
     /** Per-file upload states. */
     files: MultiUploadFileState[];
     /** Aggregated progress across all files. */
     totalProgress: UploadProgress;
+    /** Batch-level error message, or `null`. */
     error: string | null;
+    /** `true` while uploading. */
     isUploading: boolean;
+    /** Handle files from drag-and-drop or a file input. */
     handleFiles: (files: FileList | null) => void;
+    /** Open the hidden file picker. */
     openFilePicker: () => void;
+    /** Abort all in-flight uploads. */
     cancel: () => void;
+    /** Reset state to `idle`. */
     reset: () => void;
     /** Spread on a hidden `<input>` element. */
     inputProps: {

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

@@ -1,22 +1,30 @@
-import type { S3Api } from "../types/s3-api";
+import type { S3Api } from "@better-s3/core";
 import type { UploadConfig, UploadProgress, UploadRequestOptions, MultiUploadPhase, MultiUploadFileState, MultiUploadHooks } from "../types";
+/** Options for {@link useMultiUpload}. */
 export type UseMultiUploadOptions = UploadConfig & MultiUploadHooks & {
     /** S3Api client. Optional when an `<S3Provider>` is present in the tree. */
     api?: S3Api;
-    /** Static request options applied to all files */
+    /** Static request options applied to all files. */
     uploadOptions?: UploadRequestOptions;
-    /** Per-file request options (overrides uploadOptions) */
+    /** Per-file request options (overrides `uploadOptions`). */
     getUploadOptions?: (file: File) => UploadRequestOptions;
 };
 export type UseMultiUploadState = {
+    /** Current batch upload phase. */
     phase: MultiUploadPhase;
+    /** Per-file upload states. */
     files: MultiUploadFileState[];
+    /** Aggregated progress across all files. */
     totalProgress: UploadProgress;
+    /** Batch-level error message, or `null`. */
     error: string | null;
 };
 export type UseMultiUploadReturn = UseMultiUploadState & {
+    /** Upload multiple files. */
     upload: (files: File[], resolveKey: (file: File) => string) => Promise<void>;
+    /** Abort all in-flight uploads. */
     cancel: () => void;
+    /** Reset state to `idle`. */
     reset: () => void;
 };
 export declare function useMultiUpload(options: UseMultiUploadOptions): UseMultiUploadReturn;

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

@@ -1,6 +1,8 @@
 import type { UploadPhase, UploadProgress, UploadRequestOptions } from "../types";
 import { type UseUploadOptions } from "./use-upload";
+/** Options for {@link useUploadControls}. */
 export type UseUploadControlsOptions = UseUploadOptions & {
+    /** S3 object key, or a function that derives it from the file. */
     objectKey: string | ((file: File) => string);
     /** Static request options applied to the upload. */
     uploadOptions?: UploadRequestOptions;
@@ -8,17 +10,24 @@ export type UseUploadControlsOptions = UseUploadOptions & {
     getUploadOptions?: (file: File) => UploadRequestOptions;
 };
 export type UseUploadControlsReturn = {
+    /** Current upload phase. */
     phase: UploadPhase;
     /** Info about the selected file. */
     fileInfo: {
         name: string;
         size: number;
     } | null;
+    /** Byte transfer progress. */
     progress: UploadProgress;
+    /** Error message, or `null`. */
     error: string | null;
+    /** `true` while uploading. */
     isUploading: boolean;
+    /** Handle files from drag-and-drop or a file input. */
     handleFiles: (files: FileList | null) => void;
+    /** Open the hidden file picker. */
     openFilePicker: () => void;
+    /** Abort and reset to idle. */
     cancel: () => void;
     /**
      * Soft-stop: preserves S3 parts and store entry so a future `upload()` can

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

@@ -1,15 +1,22 @@
-import type { S3Api } from "../types/s3-api";
+import type { S3Api } from "@better-s3/core";
 import type { UploadConfig, UploadHooks, UploadPhase, UploadProgress, UploadResult, UploadRequestOptions } from "../types";
+/** Options for {@link useUpload}. */
 export type UseUploadOptions = UploadConfig & UploadHooks & {
     /** S3Api client. Optional when an `<S3Provider>` is present in the tree. */
     api?: S3Api;
 };
 export type UseUploadState = {
+    /** Current upload phase. */
     phase: UploadPhase;
+    /** Byte transfer progress. */
     progress: UploadProgress;
+    /** Error message, or `null`. */
     error: string | null;
+    /** Result after success, or `null`. */
     result: UploadResult | null;
+    /** Name of the file being uploaded. */
     fileName: string | null;
+    /** Size of the file being uploaded in bytes. */
     fileSize: number | null;
 };
 export type UseUploadReturn = UseUploadState & {

package/dist/index.d.ts

@@ -1,11 +1,9 @@
 export * from "./types";
-export { createS3Client, createS3Api } from "./api";
-/** @deprecated Use {@link createS3Client} instead. */
-export { createS3Api as createPresignApi } from "./api";
+export { createS3Client } 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 { formatFileSize, validateFile, parseContentDispositionFilename, formatUploadProgress, formatSpeed, formatEta, buildObjectKey, getFileExtension, truncateFilename, createSpeedTracker, type SpeedTracker, } from "./helpers";
+export { formatUploadProgress, formatSpeed, formatEta, 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";

package/dist/index.js

@@ -1,5 +1,6 @@
 import { createContext, useContext, useState, useRef, useCallback } from 'react';
 import { jsx } from 'react/jsx-runtime';
+import { formatFileSize, validateFile, parseFileName } from '@better-s3/core';
 
 // src/types/error.ts
 var S3UploadError = class extends Error {
@@ -16,7 +17,6 @@ var S3UploadError = class extends Error {
 function createS3Client(input) {
   return input;
 }
-var createS3Api = createS3Client;
 var S3Context = createContext(null);
 function S3Provider({
   client,
@@ -517,66 +517,11 @@ async function uploadFiles(api, items, config = {}, callbacks = {}, signal, getR
   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`;
 }
@@ -593,33 +538,6 @@ function formatEta(remainingBytes, bytesPerSecond) {
   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 = [];
@@ -1270,10 +1188,7 @@ function useFetchDownload(options) {
         );
       }
       const contentLength = Number(res.headers.get("content-length") || 0);
-      const name = downloadName ?? parseContentDispositionFilename(
-        res.headers.get("content-disposition"),
-        fallback
-      );
+      const name = downloadName ?? parseFileName(res.headers.get("content-disposition")) ?? fallback;
       setState((s) => ({
         ...s,
         fileName: name,
@@ -1413,6 +1328,6 @@ function useDelete(options) {
   };
 }
 
-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 };
+export { S3Context, S3Provider, S3UploadError, createLocalStorageStore, createMemoryStore, createS3Client, createSpeedTracker, formatEta, formatSpeed, formatUploadProgress, uploadFile, uploadFiles, useDelete, useDownload, useFetchDownload, useMultiUpload, useMultiUploadControls, useS3Client, useUpload, useUploadControls };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map