@better-s3/core 3.1049.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hamidreza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -0,0 +1,2 @@
+import type { S3Api } from "./types/s3-api";
+export declare function createS3Api(basePath?: string): S3Api;

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

@@ -0,0 +1,7 @@
+/**
+ * Builds a RFC 6266 `Content-Disposition` value for a file attachment.
+ *
+ * Includes both the ASCII-safe `filename` fallback and the RFC 5987
+ * `filename*` parameter for full Unicode support.
+ */
+export declare function buildContentDisposition(fileName: string): string;

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

@@ -0,0 +1 @@
+export declare function buildObjectKey(...parts: string[]): string;

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

@@ -0,0 +1 @@
+export declare function formatFileSize(bytes: number): string;

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

@@ -0,0 +1 @@
+export declare function getFileExtension(filename: string): string;

package/dist/helpers/index.d.ts

@@ -0,0 +1,8 @@
+export { validateFile } from "./validate-file";
+export { buildObjectKey } from "./build-object-key";
+export { getFileExtension } from "./get-file-extension";
+export { parseFileName } from "./parse-file-name";
+export { formatFileSize } from "./format-file-size";
+export { buildContentDisposition } from "./build-content-disposition";
+export { sanitizeFileName } from "./sanitize-file-name";
+export { truncateFilename } from "./truncate-filename";

package/dist/helpers/parse-file-name.d.ts

@@ -0,0 +1 @@
+export declare function parseFileName(contentDisposition: string | null | undefined): string | undefined;

package/dist/helpers/sanitize-file-name.d.ts

@@ -0,0 +1,2 @@
+/** Sanitizes a file name for safe use in URL query parameters. */
+export declare function sanitizeFileName(fileName: string): string;

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

@@ -0,0 +1,4 @@
+/**
+ * Truncates a filename while preserving the extension when possible.
+ */
+export declare function truncateFilename(name: string, maxChars?: number): string;

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

@@ -0,0 +1,4 @@
+export declare function validateFile(file: File, options: {
+    accept?: string[];
+    maxFileSize?: number;
+}): string | null;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types";
+export * from "./helpers";
+export { S3_API_BASE_PATH, normalizeS3ApiBasePath, S3_API_ROUTES, } from "./routes";
+export { createS3Api } from "./create-s3-api";

package/dist/index.js

@@ -0,0 +1,192 @@
+// 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/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/parse-file-name.ts
+function parseFileName(contentDisposition) {
+  if (!contentDisposition) return void 0;
+  const utf8Match = contentDisposition.match(/filename\*=UTF-8''([^;,\s]+)/i);
+  if (utf8Match) {
+    try {
+      return decodeURIComponent(utf8Match[1]);
+    } catch {
+    }
+  }
+  const asciiMatch = contentDisposition.match(/filename="([^"]*)"/i);
+  return asciiMatch?.[1];
+}
+
+// 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/build-content-disposition.ts
+function buildContentDisposition(fileName) {
+  const ascii = fileName.replace(/[^\x20-\x7E]/g, "_").replace(/["\\]/g, "_");
+  const encoded = encodeURIComponent(fileName);
+  return `attachment; filename="${ascii}"; filename*=UTF-8''${encoded}`;
+}
+
+// src/helpers/sanitize-file-name.ts
+function sanitizeFileName(fileName) {
+  return fileName.replace(/["\\\r\n]/g, "_");
+}
+
+// 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/routes.ts
+var S3_API_BASE_PATH = "/api/s3";
+function normalizeS3ApiBasePath(basePath) {
+  return basePath.replace(/\/$/, "");
+}
+var S3_API_ROUTES = {
+  upload: "presign/upload",
+  uploadConfirm: "presign/upload/confirm",
+  download: "presign/download",
+  delete: "delete",
+  multipartInit: "presign/multipart/init",
+  multipartPart: "presign/multipart/part",
+  multipartComplete: "presign/multipart/complete",
+  multipartAbort: "presign/multipart/abort",
+  multipartListParts: "presign/multipart/parts"
+};
+
+// src/create-s3-api.ts
+function createS3Api(basePath = S3_API_BASE_PATH) {
+  const base = normalizeS3ApiBasePath(basePath);
+  const json = async (url, init) => {
+    const res = await fetch(url, init);
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      throw new Error(body.message ?? res.statusText);
+    }
+    return res.json();
+  };
+  const post = (url, body) => json(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  return {
+    upload(payload) {
+      return post(
+        `${base}/${S3_API_ROUTES.upload}`,
+        payload
+      );
+    },
+    confirm(payload) {
+      return post(
+        `${base}/${S3_API_ROUTES.uploadConfirm}`,
+        payload
+      );
+    },
+    download(key, options) {
+      const params = new URLSearchParams({ key });
+      if (options?.fileName) {
+        params.set("fileName", sanitizeFileName(options.fileName));
+      }
+      if (options?.bucket) params.set("bucket", options.bucket);
+      return json(
+        `${base}/${S3_API_ROUTES.download}?${params}`
+      );
+    },
+    delete(key, options) {
+      const params = new URLSearchParams({ key });
+      if (options?.bucket) params.set("bucket", options.bucket);
+      return json(
+        `${base}/${S3_API_ROUTES.delete}?${params}`,
+        { method: "DELETE" }
+      );
+    },
+    multipart: {
+      init(payload) {
+        return post(
+          `${base}/${S3_API_ROUTES.multipartInit}`,
+          payload
+        );
+      },
+      signPart(payload) {
+        return post(
+          `${base}/${S3_API_ROUTES.multipartPart}`,
+          payload
+        );
+      },
+      listParts(payload) {
+        const params = new URLSearchParams({
+          key: payload.key,
+          uploadId: payload.uploadId
+        });
+        if (payload.bucket) params.set("bucket", payload.bucket);
+        return json(
+          `${base}/${S3_API_ROUTES.multipartListParts}?${params}`
+        );
+      },
+      complete(payload) {
+        return post(`${base}/${S3_API_ROUTES.multipartComplete}`, payload);
+      },
+      abort(payload) {
+        return post(
+          `${base}/${S3_API_ROUTES.multipartAbort}`,
+          payload
+        );
+      }
+    }
+  };
+}
+
+export { S3_API_BASE_PATH, S3_API_ROUTES, buildContentDisposition, buildObjectKey, createS3Api, formatFileSize, getFileExtension, normalizeS3ApiBasePath, parseFileName, sanitizeFileName, truncateFilename, validateFile };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/helpers/validate-file.ts","../src/helpers/build-object-key.ts","../src/helpers/get-file-extension.ts","../src/helpers/parse-file-name.ts","../src/helpers/format-file-size.ts","../src/helpers/build-content-disposition.ts","../src/helpers/sanitize-file-name.ts","../src/helpers/truncate-filename.ts","../src/routes.ts","../src/create-s3-api.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["export function validateFile(\n  file: File,\n  options: { accept?: string[]; maxFileSize?: number },\n): string | null {\n  if (options.accept?.length) {\n    const allowed = options.accept.some((type) => {\n      if (type.startsWith(\".\")) {\n        return file.name.toLowerCase().endsWith(type.toLowerCase());\n      }\n      if (type.endsWith(\"/*\")) {\n        return file.type.startsWith(type.replace(\"/*\", \"/\"));\n      }\n      return file.type === type;\n    });\n    if (!allowed) {\n      const ext = file.name.includes(\".\") ? file.name.split(\".\").pop() : null;\n      return `File type \"${ext ? `.${ext}` : file.type || \"unknown\"}\" is not allowed`;\n    }\n  }\n\n  if (file.size === 0) {\n    return \"File is empty\";\n  }\n\n  if (options.maxFileSize && file.size > options.maxFileSize) {\n    const maxMB = (options.maxFileSize / (1024 * 1024)).toFixed(1);\n    return `File size exceeds ${maxMB} MB limit`;\n  }\n\n  return null;\n}\n","export function buildObjectKey(...parts: string[]): string {\n  return parts\n    .map((p) => p.replace(/^\\/+|\\/+$/g, \"\"))\n    .filter(Boolean)\n    .join(\"/\");\n}\n","export function getFileExtension(filename: string): string {\n  const dotIndex = filename.lastIndexOf(\".\");\n  if (dotIndex < 1) return \"\";\n  return filename.slice(dotIndex + 1).toLowerCase();\n}\n","export function parseFileName(\n  contentDisposition: string | null | undefined,\n): string | undefined {\n  if (!contentDisposition) return undefined;\n\n  const utf8Match = contentDisposition.match(/filename\\*=UTF-8''([^;,\\s]+)/i);\n  if (utf8Match) {\n    try {\n      return decodeURIComponent(utf8Match[1]);\n    } catch {\n      /* ignore malformed encoding */\n    }\n  }\n\n  const asciiMatch = contentDisposition.match(/filename=\"([^\"]*)\"/i);\n  return asciiMatch?.[1];\n}\n","export function formatFileSize(bytes: number): string {\n  if (bytes === 0) return \"0 B\";\n  const units = [\"B\", \"KB\", \"MB\", \"GB\", \"TB\"];\n  const i = Math.floor(Math.log(bytes) / Math.log(1024));\n  const size = bytes / Math.pow(1024, i);\n  return `${size.toFixed(i === 0 ? 0 : 1)} ${units[i]}`;\n}\n","/**\n * Builds a RFC 6266 `Content-Disposition` value for a file attachment.\n *\n * Includes both the ASCII-safe `filename` fallback and the RFC 5987\n * `filename*` parameter for full Unicode support.\n */\nexport function buildContentDisposition(fileName: string): string {\n  const ascii = fileName.replace(/[^\\x20-\\x7E]/g, \"_\").replace(/[\"\\\\]/g, \"_\");\n  const encoded = encodeURIComponent(fileName);\n  return `attachment; filename=\"${ascii}\"; filename*=UTF-8''${encoded}`;\n}\n","/** Sanitizes a file name for safe use in URL query parameters. */\nexport function sanitizeFileName(fileName: string): string {\n  return fileName.replace(/[\"\\\\\\r\\n]/g, \"_\");\n}\n","/**\n * Truncates a filename while preserving the extension when possible.\n */\nexport function truncateFilename(name: string, maxChars = 26): string {\n  if (name.length <= maxChars) return name;\n  const dotIndex = name.lastIndexOf(\".\");\n  if (dotIndex <= 0) {\n    return name.slice(0, maxChars - 1) + \"…\";\n  }\n  const ext = name.slice(dotIndex);\n  const available = maxChars - ext.length - 1;\n  if (available <= 0) {\n    return name.slice(0, maxChars - 1) + \"…\";\n  }\n  return name.slice(0, available) + \"… \" + ext;\n}\n","/** Default mount path for the catch-all route (`app/api/s3/[...s3]/route.ts`). */\nexport const S3_API_BASE_PATH = \"/api/s3\";\n\nexport function normalizeS3ApiBasePath(basePath: string): string {\n  return basePath.replace(/\\/$/, \"\");\n}\n\nexport const S3_API_ROUTES = {\n  upload: \"presign/upload\",\n  uploadConfirm: \"presign/upload/confirm\",\n  download: \"presign/download\",\n  delete: \"delete\",\n  multipartInit: \"presign/multipart/init\",\n  multipartPart: \"presign/multipart/part\",\n  multipartComplete: \"presign/multipart/complete\",\n  multipartAbort: \"presign/multipart/abort\",\n  multipartListParts: \"presign/multipart/parts\",\n} as const;\n","import type {\n  MultipartInitResponse,\n  MultipartListPartsResponse,\n  MultipartPartResponse,\n  PresignResponse,\n  S3Api,\n  UploadConfirmResponse,\n  UploadPresignResponse,\n} from \"./types/s3-api\";\nimport { sanitizeFileName } from \"./helpers/sanitize-file-name\";\nimport {\n  normalizeS3ApiBasePath,\n  S3_API_BASE_PATH,\n  S3_API_ROUTES,\n} from \"./routes\";\n\nexport function createS3Api(basePath: string = S3_API_BASE_PATH): S3Api {\n  const base = normalizeS3ApiBasePath(basePath);\n\n  const json = async <T>(url: string, init?: RequestInit): Promise<T> => {\n    const res = await fetch(url, init);\n    if (!res.ok) {\n      const body = await res.json().catch(() => ({}));\n      throw new Error((body as { message?: string }).message ?? res.statusText);\n    }\n    return res.json() as Promise<T>;\n  };\n\n  const post = <T>(url: string, body: unknown): Promise<T> =>\n    json<T>(url, {\n      method: \"POST\",\n      headers: { \"Content-Type\": \"application/json\" },\n      body: JSON.stringify(body),\n    });\n\n  return {\n    upload(payload) {\n      return post<UploadPresignResponse>(\n        `${base}/${S3_API_ROUTES.upload}`,\n        payload,\n      );\n    },\n\n    confirm(payload) {\n      return post<UploadConfirmResponse>(\n        `${base}/${S3_API_ROUTES.uploadConfirm}`,\n        payload,\n      );\n    },\n\n    download(key, options?) {\n      const params = new URLSearchParams({ key });\n      if (options?.fileName) {\n        params.set(\"fileName\", sanitizeFileName(options.fileName));\n      }\n      if (options?.bucket) params.set(\"bucket\", options.bucket);\n      return json<PresignResponse>(\n        `${base}/${S3_API_ROUTES.download}?${params}`,\n      );\n    },\n\n    delete(key, options?) {\n      const params = new URLSearchParams({ key });\n      if (options?.bucket) params.set(\"bucket\", options.bucket);\n      return json<{ success: boolean; bucket: string; key: string }>(\n        `${base}/${S3_API_ROUTES.delete}?${params}`,\n        { method: \"DELETE\" },\n      );\n    },\n\n    multipart: {\n      init(payload) {\n        return post<MultipartInitResponse>(\n          `${base}/${S3_API_ROUTES.multipartInit}`,\n          payload,\n        );\n      },\n\n      signPart(payload) {\n        return post<MultipartPartResponse>(\n          `${base}/${S3_API_ROUTES.multipartPart}`,\n          payload,\n        );\n      },\n\n      listParts(payload) {\n        const params = new URLSearchParams({\n          key: payload.key,\n          uploadId: payload.uploadId,\n        });\n        if (payload.bucket) params.set(\"bucket\", payload.bucket);\n        return json<MultipartListPartsResponse>(\n          `${base}/${S3_API_ROUTES.multipartListParts}?${params}`,\n        );\n      },\n\n      complete(payload) {\n        return post<{\n          key: string;\n          bucket: string;\n          uploadId: string;\n          contentLength: number;\n          contentType?: string;\n          eTag?: string;\n          metadata: Record<string, string>;\n        }>(`${base}/${S3_API_ROUTES.multipartComplete}`, payload);\n      },\n\n      abort(payload) {\n        return post<{ aborted: boolean }>(\n          `${base}/${S3_API_ROUTES.multipartAbort}`,\n          payload,\n        );\n      },\n    },\n  };\n}\n"]}

package/dist/routes.d.ts

@@ -0,0 +1,14 @@
+/** Default mount path for the catch-all route (`app/api/s3/[...s3]/route.ts`). */
+export declare const S3_API_BASE_PATH = "/api/s3";
+export declare function normalizeS3ApiBasePath(basePath: string): string;
+export declare const S3_API_ROUTES: {
+    readonly upload: "presign/upload";
+    readonly uploadConfirm: "presign/upload/confirm";
+    readonly download: "presign/download";
+    readonly delete: "delete";
+    readonly multipartInit: "presign/multipart/init";
+    readonly multipartPart: "presign/multipart/part";
+    readonly multipartComplete: "presign/multipart/complete";
+    readonly multipartAbort: "presign/multipart/abort";
+    readonly multipartListParts: "presign/multipart/parts";
+};

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export type { UploadPresignMethod } from "./upload-presign-method";
+export type { S3ObjectAcl, UploadPayload, ConfirmPayload, DownloadOptions, DeleteOptions, DeleteResponse, MultipartInitPayload, MultipartSignPartPayload, MultipartListPartsPayload, MultipartCompletedPartRef, MultipartCompletePayload, MultipartCompleteResponse, MultipartAbortPayload, MultipartAbortResponse, } from "./s3-payloads";
+export type { PresignResponse, UploadPresignResponse, MultipartInitResponse, MultipartPartResponse, MultipartPartInfo, MultipartListPartsResponse, UploadConfirmResponse, S3Api, } from "./s3-api";

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

@@ -0,0 +1,109 @@
+import type { UploadPresignMethod } from "./upload-presign-method";
+import type { ConfirmPayload, DeleteOptions, DeleteResponse, DownloadOptions, MultipartAbortPayload, MultipartAbortResponse, MultipartCompletePayload, MultipartCompleteResponse, MultipartInitPayload, MultipartListPartsPayload, MultipartSignPartPayload, S3ObjectAcl, UploadPayload } from "./s3-payloads";
+export type { S3ObjectAcl } from "./s3-payloads";
+/** Presigned GET URL for download. */
+export type PresignResponse = {
+    /** S3 object key. */
+    key: string;
+    /** Target bucket. */
+    bucket: string;
+    /** Presigned URL. */
+    url: string;
+    /** Validity in seconds. */
+    expiresIn: number;
+};
+/** Presigned upload URL and method-specific fields. */
+export type UploadPresignResponse = {
+    /** S3 object key. */
+    key: string;
+    /** Target bucket. */
+    bucket: string;
+    /** Presigned upload URL. */
+    url: string;
+    /** Validity in seconds. */
+    expiresIn: number;
+    /** HTTP method for the upload request. */
+    method: UploadPresignMethod;
+    /** 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>;
+};
+/** Response from multipart upload initialization. */
+export type MultipartInitResponse = {
+    /** S3 object key. */
+    key: string;
+    /** Target bucket. */
+    bucket: string;
+    /** S3 multipart upload ID. */
+    uploadId: string;
+};
+/** Presigned URL for a single multipart part. */
+export type MultipartPartResponse = {
+    /** Presigned PUT URL for this part. */
+    presignedUrl: string;
+    /** 1-based part number. */
+    partNumber: number;
+    /** Multipart upload ID. */
+    uploadId: string;
+    /** Target bucket. */
+    bucket: string;
+    /** Validity in seconds. */
+    expiresIn: number;
+    /** Exact byte size locked into this part's presigned URL signature. */
+    partSize?: number;
+};
+/** A part already uploaded in a multipart session. */
+export type MultipartPartInfo = {
+    /** 1-based part number. */
+    partNumber: number;
+    /** Part size in bytes. */
+    size: number;
+    /** Part ETag from S3. */
+    eTag: string;
+};
+/** Response from listing uploaded multipart parts. */
+export type MultipartListPartsResponse = {
+    parts: MultipartPartInfo[];
+};
+/** Verified object metadata after upload confirmation. */
+export type UploadConfirmResponse = {
+    /** S3 object key. */
+    key: string;
+    /** Target bucket. */
+    bucket: string;
+    /** MIME type from HeadObject. */
+    contentType?: string;
+    /** Verified size in bytes. */
+    contentLength: number;
+    /** ETag from HeadObject. */
+    eTag?: string;
+    /** Object metadata. */
+    metadata: Record<string, string>;
+    /** Object ACL. */
+    acl?: S3ObjectAcl;
+    /** Stored filename. */
+    fileName?: string;
+    /** S3 version ID. */
+    versionId?: string;
+    /** Last modified timestamp. */
+    lastModified?: string;
+};
+/**
+ * Presign API protocol shared by `@better-s3/react` hooks and `@better-s3/server`.
+ *
+ * Implement with `createS3Api()` from `@better-s3/core`, or any custom backend.
+ */
+export type S3Api = {
+    upload: (payload: UploadPayload) => Promise<UploadPresignResponse>;
+    confirm: (payload: ConfirmPayload) => Promise<UploadConfirmResponse>;
+    download: (key: string, options?: DownloadOptions) => Promise<PresignResponse>;
+    delete: (key: string, options?: DeleteOptions) => Promise<DeleteResponse>;
+    multipart: {
+        init: (payload: MultipartInitPayload) => Promise<MultipartInitResponse>;
+        signPart: (payload: MultipartSignPartPayload) => Promise<MultipartPartResponse>;
+        listParts: (payload: MultipartListPartsPayload) => Promise<MultipartListPartsResponse>;
+        complete: (payload: MultipartCompletePayload) => Promise<MultipartCompleteResponse>;
+        abort: (payload: MultipartAbortPayload) => Promise<MultipartAbortResponse>;
+    };
+};

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

@@ -0,0 +1,110 @@
+/** S3 object ACL. */
+export type S3ObjectAcl = "private" | "public-read";
+/** Payload for {@link S3Api.upload}. */
+export type UploadPayload = {
+    /** S3 object key. */
+    key: string;
+    /** Declared MIME type. */
+    contentType?: string;
+    /** Declared size in bytes. */
+    fileSize?: number;
+    /** Custom object metadata (`x-amz-meta-*`). */
+    metadata?: Record<string, string>;
+    /** Override default bucket. */
+    bucket?: string;
+    /** Requested ACL. */
+    acl?: S3ObjectAcl;
+    /** Original filename for `Content-Disposition`. */
+    fileName?: string;
+};
+/** Payload for {@link S3Api.confirm}. */
+export type ConfirmPayload = {
+    /** S3 object key. */
+    key: string;
+    /** Override default bucket. */
+    bucket?: string;
+};
+/** Options for {@link S3Api.download}. */
+export type DownloadOptions = {
+    /** Download filename for `Content-Disposition`. */
+    fileName?: string;
+    /** Override default bucket. */
+    bucket?: string;
+};
+/** Options for {@link S3Api.delete}. */
+export type DeleteOptions = {
+    /** Override default bucket. */
+    bucket?: string;
+};
+/** Response from {@link S3Api.delete}. */
+export type DeleteResponse = {
+    success: boolean;
+    bucket: string;
+    key: string;
+};
+/** Payload for {@link S3Api.multipart.init}. Same fields as {@link UploadPayload}. */
+export type MultipartInitPayload = UploadPayload;
+/** Payload for {@link S3Api.multipart.signPart}. */
+export type MultipartSignPartPayload = {
+    /** S3 object key. */
+    key: string;
+    /** Multipart upload ID. */
+    uploadId: string;
+    /** 1-based part number. */
+    partNumber: number;
+    /** Byte size locked into the presigned URL signature. */
+    partSize?: number;
+    /** Override default bucket. */
+    bucket?: string;
+};
+/** Payload for {@link S3Api.multipart.listParts}. */
+export type MultipartListPartsPayload = {
+    /** S3 object key. */
+    key: string;
+    /** Multipart upload ID. */
+    uploadId: string;
+    /** Override default bucket. */
+    bucket?: string;
+};
+/** A completed multipart part reference for {@link S3Api.multipart.complete}. */
+export type MultipartCompletedPartRef = {
+    /** 1-based part number. */
+    partNumber: number;
+};
+/** Payload for {@link S3Api.multipart.complete}. */
+export type MultipartCompletePayload = {
+    /** S3 object key. */
+    key: string;
+    /** Multipart upload ID. */
+    uploadId: string;
+    /** Parts to assemble (order does not matter — S3 sorts by part number). */
+    parts: MultipartCompletedPartRef[];
+    /** Override default bucket. */
+    bucket?: string;
+};
+/** Response from {@link S3Api.multipart.complete}. */
+export type MultipartCompleteResponse = {
+    key: string;
+    bucket: string;
+    uploadId: string;
+    /** Verified size in bytes. */
+    contentLength: number;
+    contentType?: string;
+    eTag?: string;
+    metadata: Record<string, string>;
+    versionId?: string;
+    lastModified?: string;
+};
+/** Payload for {@link S3Api.multipart.abort}. */
+export type MultipartAbortPayload = {
+    /** S3 object key. */
+    key: string;
+    /** Multipart upload ID. */
+    uploadId: string;
+    /** Override default bucket. */
+    bucket?: string;
+};
+/** Response from {@link S3Api.multipart.abort}. */
+export type MultipartAbortResponse = {
+    aborted: boolean;
+};

package/dist/types/upload-presign-method.d.ts

@@ -0,0 +1,2 @@
+/** HTTP method used for a presigned upload URL. */
+export type UploadPresignMethod = "POST" | "PUT";

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@better-s3/core",
+  "version": "3.1049.0",
+  "description": "Shared types and pure helpers for @better-s3/react and @better-s3/server",
+  "keywords": [
+    "s3",
+    "types",
+    "upload",
+    "file-upload"
+  ],
+  "author": "Hamidrezakz",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hamidrezakz/better-s3.git",
+    "directory": "packages/better-s3-core"
+  },
+  "homepage": "https://github.com/hamidrezakz/better-s3/tree/master/packages/better-s3-core",
+  "bugs": {
+    "url": "https://github.com/hamidrezakz/better-s3/issues"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup --config tsup.config.ts && tsc --emitDeclarationOnly",
+    "check-types": "tsc --noEmit"
+  }
+}