@better-s3/react 3.1048.0 → 3.1050.0

package/dist/s3-provider.d.ts

@@ -1,5 +1,5 @@
 import { type ReactNode } from "react";
-import type { S3Api } from "./types/s3-api";
+import type { S3Api } from "@better-s3/core";
 /**
  * Internal context — use `S3Provider` to supply and `useS3Client` to consume.
  * Exported so hooks can call `useContext(S3Context)` directly without throwing
@@ -15,7 +15,7 @@ export declare const S3Context: import("react").Context<S3Api | null>;
  * @example
  * ```tsx
  * // With @better-s3/server:
- * import { createS3Api } from "@better-s3/server";
+ * import { createS3Api } from "@better-s3/core";
  * import { S3Provider } from "@better-s3/react";
  *
  * const s3Client = createS3Api();
@@ -24,10 +24,10 @@ export declare const S3Context: import("react").Context<S3Api | null>;
  *   return <S3Provider client={s3Client}>{children}</S3Provider>;
  * }
  *
- * // With a custom server (use createS3Client for a compatible fetch client):
- * import { createS3Client, S3Provider } from "@better-s3/react";
+ * // Custom base path:
+ * import { createS3Api } from "@better-s3/core";
  *
- * const s3Client = createS3Client("/api/my-s3");
+ * const s3Client = createS3Api("/api/my-s3");
  *
  * export function Providers({ children }: { children: React.ReactNode }) {
  *   return <S3Provider client={s3Client}>{children}</S3Provider>;
@@ -37,7 +37,7 @@ export declare const S3Context: import("react").Context<S3Api | null>;
 export declare function S3Provider({ client, children, }: {
     client: S3Api;
     children: ReactNode;
-}): import("react/jsx-runtime").JSX.Element;
+}): import("react").JSX.Element;
 /**
  * Returns the `S3Api` client from the nearest `S3Provider`.
  * Throws if called outside a provider and no `api` prop was given to the hook.

package/dist/types/delete.d.ts

@@ -1,6 +1,9 @@
 export type DeletePhase = "idle" | "confirming" | "deleting" | "success" | "error";
+/** Lifecycle hooks for delete. */
 export type DeleteHooks = {
+    /** Runs before delete. Return `false` to block it. */
     beforeDelete?: (key: string) => Promise<boolean> | boolean;
+    /** Fires when delete begins (after confirmation). */
     onDeleteStart?: (key: string) => void;
     onSuccess?: (key: string) => Promise<void> | void;
     onError?: (key: string, error: unknown, phase: DeletePhase) => void;

package/dist/types/download.d.ts

@@ -1,6 +1,8 @@
 import type { UploadProgress } from "./upload";
 export type DownloadPhase = "idle" | "presigning" | "error";
+/** Lifecycle hooks for presign-and-navigate download. */
 export type DownloadHooks = {
+    /** Runs before presigning. Return `false` to block the download. */
     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;
@@ -9,11 +11,15 @@ export type DownloadHooks = {
 export type FetchDownloadPhase = "idle" | "presigning" | "downloading" | "success" | "error";
 /** Identical shape to {@link UploadProgress}. */
 export type FetchDownloadProgress = UploadProgress;
+/** Lifecycle hooks for fetch-based download with progress. */
 export type FetchDownloadHooks = {
+    /** Runs before presigning. Return `false` to block the download. */
     beforeDownload?: (key: string) => Promise<boolean> | boolean;
+    /** Fires when the byte transfer begins. */
     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;
+    /** Fires when cancelled via `cancel()`. */
     onCancel?: (key: string) => void;
 };

package/dist/types/index.d.ts

@@ -1,4 +1,3 @@
-export * from "./s3-api";
 export * from "./upload";
 export * from "./upload-store";
 export * from "./error";

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

@@ -1,13 +1,18 @@
 import type { UploadProgress, UploadResult } from "./upload";
 export type MultiUploadPhase = "idle" | "validating" | "uploading" | "success" | "error";
+/** Per-file state in a multi-upload batch. */
 export type MultiUploadFileState = {
+    /** Unique ID for this file in the batch. */
     id: string;
+    /** Display file name. */
     fileName: string;
+    /** File size in bytes. */
     fileSize: number;
     status: "pending" | "uploading" | "success" | "error";
     progress: UploadProgress;
     error: string | null;
 };
+/** Lifecycle hooks for multi-file upload. */
 export type MultiUploadHooks = {
     beforeUpload?: (files: File[]) => Promise<boolean> | boolean;
     onUploadStart?: (files: File[]) => void;

package/dist/types/upload.d.ts

@@ -1,25 +1,34 @@
 import type { UploadStore } from "./upload-store";
+/** Result returned after a successful upload. */
 export type UploadResult = {
+    /** S3 object key. */
     key: string;
+    /** Public or presigned URL, when available. */
     url?: string;
+    /** Object ETag from S3. */
     eTag?: string;
 };
+/** Byte transfer progress for upload and fetch-download. */
 export type UploadProgress = {
+    /** Bytes transferred so far. */
     loaded: number;
+    /** Total bytes to transfer. */
     total: number;
+    /** Progress percentage (0–100). */
     percent: number;
     /** Instantaneous transfer speed in bytes/second. `undefined` until measurable. */
     speed?: number;
 };
 export type UploadPhase = "idle" | "validating" | "presigning" | "uploading" | "finalizing" | "success" | "error";
+/** Per-upload options passed to the presign API. */
 export type UploadRequestOptions = {
-    /** Custom S3 object metadata (x-amz-meta-*) */
+    /** Custom S3 object metadata (`x-amz-meta-*`). */
     metadata?: Record<string, string>;
-    /** Target bucket (overrides server default) */
+    /** Target bucket (overrides server default). */
     bucket?: string;
-    /** Override auto-detected content type */
+    /** Override auto-detected content type. */
     contentType?: string;
-    /** Object ACL – defaults to `'private'` */
+    /** Object ACL — defaults to `'private'`. */
     acl?: "private" | "public-read";
     /**
      * Original file name stored as `Content-Disposition` on the S3 object.
@@ -33,6 +42,7 @@ export type UploadRequestOptions = {
      */
     partSize?: number;
 };
+/** Lifecycle hooks for single-file upload. */
 export type UploadHooks = {
     /** Runs before the upload starts. Return `false` to block it. */
     beforeUpload?: (file: File) => Promise<boolean> | boolean;
@@ -40,16 +50,9 @@ export type UploadHooks = {
     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`).
-     */
+    /** Fires after each part is successfully uploaded to S3 (multipart only). */
     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.
-     */
+    /** Fires once after `CreateMultipartUpload` succeeds (multipart only). */
     onMultipartInit?: (file: File, uploadId: string) => void;
     /** Fires when the upload finishes successfully. */
     onSuccess?: (file: File, result: UploadResult) => Promise<void> | void;
@@ -58,17 +61,24 @@ export type UploadHooks = {
     /** Fires when the upload is cancelled via `cancel()`. */
     onCancel?: (file: File | null) => void;
 };
+/** Retry configuration for failed network requests. */
 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;
 };
+/** Upload engine configuration for `useUpload` and `useMultiUpload`. */
 export type UploadConfig = {
+    /** Enable multipart uploads for large files. */
     multipart?: boolean;
+    /** Allowed file extensions or MIME types. */
     accept?: string[];
+    /** Max file size in bytes. */
     maxFileSize?: number;
+    /** Max number of files (multi-upload). */
     maxFiles?: number;
+    /** File size threshold in bytes above which multipart is used. */
     multipartThreshold?: number;
     /**
      * Multipart part size in bytes. Minimum 5 MB.
@@ -76,25 +86,18 @@ export type UploadConfig = {
      * @default 5 MB
      */
     partSize?: number;
+    /** Number of parts uploaded concurrently (multipart). */
     concurrentParts?: number;
+    /** Number of files uploaded concurrently (multi-upload). */
     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 });
-     * ```
+     * - Omit / `undefined` — abort immediately on cancel or error.
+     * - `false` — same as omitting.
+     * - Custom `UploadStore` — persist `uploadId` across sessions.
      */
     uploadStore?: UploadStore | false;
 };

package/dist/upload/multipart.d.ts

@@ -1,4 +1,4 @@
 import type { UploadProgress, UploadRequestOptions, RetryConfig } from "../types";
-import type { S3Api } from "../types/s3-api";
+import type { S3Api } from "@better-s3/core";
 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/upload-file.d.ts

@@ -1,5 +1,5 @@
 import type { UploadConfig, UploadProgress, UploadResult, UploadRequestOptions } from "../types";
-import type { S3Api } from "../types/s3-api";
+import type { S3Api } from "@better-s3/core";
 export type UploadEngineCallbacks = {
     onProgress?: (progress: UploadProgress) => void;
     /** Called when the upload transitions between internal phases. */

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

@@ -1,5 +1,5 @@
 import type { UploadConfig, UploadProgress, UploadResult, UploadRequestOptions } from "../types";
-import type { S3Api } from "../types/s3-api";
+import type { S3Api } from "@better-s3/core";
 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.1048.0",
+  "version": "3.1050.0",
   "description": "React hooks for S3-compatible file uploads, downloads, and deletes",
   "keywords": [
     "s3",
@@ -32,12 +32,15 @@
   "files": [
     "dist"
   ],
+  "dependencies": {
+    "@better-s3/core": "3.1050.0"
+  },
   "peerDependencies": {
     "react": ">=18"
   },
   "devDependencies": {
-    "@types/react": "^19.2.15",
-    "react": "^19.2.6",
+    "@types/react": "^19.2.17",
+    "react": "^19.2.7",
     "tsup": "^8.5.1",
     "typescript": "6.0.3"
   },

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

@@ -1,20 +0,0 @@
-/**
- * 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-file-size.d.ts

@@ -1,11 +0,0 @@
-/**
- * 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/get-file-extension.d.ts

@@ -1,13 +0,0 @@
-/**
- * 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/parse-content-disposition.d.ts

@@ -1,18 +0,0 @@
-/**
- * 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/truncate-filename.d.ts

@@ -1,9 +0,0 @@
-/**
- * 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

@@ -1,22 +0,0 @@
-/**
- * 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/types/s3-api.d.ts

@@ -1,158 +0,0 @@
-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;
-        }>;
-    };
-};