@better-s3/server 3.1048.0 → 3.1049.0

package/dist/api.d.ts

@@ -1,154 +0,0 @@
-import type { UploadPresignMethod } from "./types/upload-presign-method";
-export type PresignResponse = {
-    key: string;
-    bucket: string;
-    url: string;
-    expiresIn: number;
-};
-export type UploadPresignResponse = {
-    key: string;
-    bucket: string;
-    url: string;
-    expiresIn: number;
-    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>;
-};
-/** @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. Only present when partSize was supplied to signPart. */
-    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;
-};
-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. Used for quota/guard checks and stored in `onInit` context. */
-            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;
-        }>;
-    };
-};
-export declare function createS3Api(basePath?: string): S3Api;

package/dist/constants.d.ts

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

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

@@ -1,13 +0,0 @@
-/**
- * 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, so the original file
- * name (including non-ASCII characters) is preserved across all browsers
- * and HTTP clients.
- *
- * @example
- * buildContentDisposition("résumé finale.pdf")
- * // → 'attachment; filename="resume finale.pdf"; filename*=UTF-8\'\'r%C3%A9sum%C3%A9%20finale.pdf'
- */
-export declare function buildContentDisposition(fileName: string): string;

package/dist/helpers/index.js

@@ -1,24 +0,0 @@
-// 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/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];
-}
-
-export { buildContentDisposition, parseFileName };
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

package/dist/helpers/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../src/helpers/build-content-disposition.ts","../../src/helpers/parse-file-name.ts"],"names":[],"mappings":";AAYO,SAAS,wBAAwB,QAAA,EAA0B;AAChE,EAAA,MAAM,KAAA,GAAQ,SAAS,OAAA,CAAQ,eAAA,EAAiB,GAAG,CAAA,CAAE,OAAA,CAAQ,UAAU,GAAG,CAAA;AAC1E,EAAA,MAAM,OAAA,GAAU,mBAAmB,QAAQ,CAAA;AAC3C,EAAA,OAAO,CAAA,sBAAA,EAAyB,KAAK,CAAA,oBAAA,EAAuB,OAAO,CAAA,CAAA;AACrE;;;ACRO,SAAS,cACd,kBAAA,EACoB;AACpB,EAAA,IAAI,CAAC,oBAAoB,OAAO,MAAA;AAEhC,EAAA,MAAM,SAAA,GAAY,kBAAA,CAAmB,KAAA,CAAM,8BAA8B,CAAA;AACzE,EAAA,IAAI,SAAA,EAAW;AACb,IAAA,IAAI;AACF,MAAA,OAAO,kBAAA,CAAmB,SAAA,CAAU,CAAC,CAAC,CAAA;AAAA,IACxC,CAAA,CAAA,MAAQ;AAAA,IAER;AAAA,EACF;AAEA,EAAA,MAAM,UAAA,GAAa,kBAAA,CAAmB,KAAA,CAAM,qBAAqB,CAAA;AACjE,EAAA,OAAO,aAAa,CAAC,CAAA;AACvB","file":"index.js","sourcesContent":["/**\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, so the original file\n * name (including non-ASCII characters) is preserved across all browsers\n * and HTTP clients.\n *\n * @example\n * buildContentDisposition(\"résumé finale.pdf\")\n * // → 'attachment; filename=\"resume finale.pdf\"; filename*=UTF-8\\'\\'r%C3%A9sum%C3%A9%20finale.pdf'\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","/**\n * Parses the display file name from a `Content-Disposition` header value.\n *\n * Prefers the RFC 5987 `filename*=UTF-8''…` encoding (full Unicode) over\n * the plain ASCII `filename=\"…\"` fallback.\n *\n * Returns `undefined` when no filename can be extracted.\n */\nexport function parseFileName(\n  contentDisposition: string | 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"]}

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

@@ -1,9 +0,0 @@
-/**
- * Parses the display file name from a `Content-Disposition` header value.
- *
- * Prefers the RFC 5987 `filename*=UTF-8''…` encoding (full Unicode) over
- * the plain ASCII `filename="…"` fallback.
- *
- * Returns `undefined` when no filename can be extracted.
- */
-export declare function parseFileName(contentDisposition: string | undefined): string | undefined;

package/dist/helpers/server/index.d.ts

@@ -1 +0,0 @@
-export { resolveObjectAcl } from "./resolve-object-acl";

package/dist/helpers/server/index.js

@@ -1,26 +0,0 @@
-import { GetObjectAclCommand } from '@aws-sdk/client-s3';
-
-// src/helpers/server/resolve-object-acl.ts
-var DEFAULT_ACL_LOOKUP_TIMEOUT_MS = 1500;
-async function resolveObjectAcl(s3, bucket, key, timeoutMs = DEFAULT_ACL_LOOKUP_TIMEOUT_MS) {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    const result = await s3.send(
-      new GetObjectAclCommand({ Bucket: bucket, Key: key }),
-      { abortSignal: controller.signal }
-    );
-    const isPublic = result.Grants?.some(
-      (g) => g.Grantee?.URI === "http://acs.amazonaws.com/groups/global/AllUsers" && (g.Permission === "READ" || g.Permission === "FULL_CONTROL")
-    );
-    return isPublic ? "public-read" : "private";
-  } catch {
-    return void 0;
-  } finally {
-    clearTimeout(timeout);
-  }
-}
-
-export { resolveObjectAcl };
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

package/dist/helpers/server/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../../src/helpers/server/resolve-object-acl.ts"],"names":[],"mappings":";;;AAEA,IAAM,6BAAA,GAAgC,IAAA;AAStC,eAAsB,gBAAA,CACpB,EAAA,EACA,MAAA,EACA,GAAA,EACA,YAAoB,6BAAA,EAC4B;AAChD,EAAA,MAAM,UAAA,GAAa,IAAI,eAAA,EAAgB;AACvC,EAAA,MAAM,UAAU,UAAA,CAAW,MAAM,UAAA,CAAW,KAAA,IAAS,SAAS,CAAA;AAE9D,EAAA,IAAI;AACF,IAAA,MAAM,MAAA,GAAS,MAAM,EAAA,CAAG,IAAA;AAAA,MACtB,IAAI,mBAAA,CAAoB,EAAE,QAAQ,MAAA,EAAQ,GAAA,EAAK,KAAK,CAAA;AAAA,MACpD,EAAE,WAAA,EAAa,UAAA,CAAW,MAAA;AAAO,KACnC;AACA,IAAA,MAAM,QAAA,GAAW,OAAO,MAAA,EAAQ,IAAA;AAAA,MAC9B,CAAC,CAAA,KACC,CAAA,CAAE,OAAA,EAAS,GAAA,KAAQ,sDAClB,CAAA,CAAE,UAAA,KAAe,MAAA,IAAU,CAAA,CAAE,UAAA,KAAe,cAAA;AAAA,KACjD;AACA,IAAA,OAAO,WAAW,aAAA,GAAgB,SAAA;AAAA,EACpC,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,MAAA;AAAA,EACT,CAAA,SAAE;AACA,IAAA,YAAA,CAAa,OAAO,CAAA;AAAA,EACtB;AACF","file":"index.js","sourcesContent":["import { GetObjectAclCommand, type S3Client } from \"@aws-sdk/client-s3\";\n\nconst DEFAULT_ACL_LOOKUP_TIMEOUT_MS = 1_500;\n\n/**\n * Determines the ACL of an S3 object by querying `GetObjectAcl`.\n *\n * Returns `\"public-read\"` when the `AllUsers` grantee has `READ` or\n * `FULL_CONTROL` permission, `\"private\"` when ACL is resolvable but not public,\n * and `undefined` when ACL cannot be resolved (e.g. unsupported providers).\n */\nexport async function resolveObjectAcl(\n  s3: S3Client,\n  bucket: string,\n  key: string,\n  timeoutMs: number = DEFAULT_ACL_LOOKUP_TIMEOUT_MS,\n): Promise<\"public-read\" | \"private\" | undefined> {\n  const controller = new AbortController();\n  const timeout = setTimeout(() => controller.abort(), timeoutMs);\n\n  try {\n    const result = await s3.send(\n      new GetObjectAclCommand({ Bucket: bucket, Key: key }),\n      { abortSignal: controller.signal },\n    );\n    const isPublic = result.Grants?.some(\n      (g) =>\n        g.Grantee?.URI === \"http://acs.amazonaws.com/groups/global/AllUsers\" &&\n        (g.Permission === \"READ\" || g.Permission === \"FULL_CONTROL\"),\n    );\n    return isPublic ? \"public-read\" : \"private\";\n  } catch {\n    return undefined;\n  } finally {\n    clearTimeout(timeout);\n  }\n}\n"]}

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

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

package/dist/types/delete-hook-context.d.ts

@@ -1,5 +0,0 @@
-import type { HookContext } from "./hook-context";
-export type DeleteHookContext = HookContext & {
-    key: string;
-    bucket: string;
-};

package/dist/types/download-hook-context.d.ts

@@ -1,6 +0,0 @@
-import type { HookContext } from "./hook-context";
-export type DownloadHookContext = HookContext & {
-    key: string;
-    bucket: string;
-    fileName?: string;
-};

package/dist/types/download-success-context.d.ts

@@ -1,5 +0,0 @@
-import type { DownloadHookContext } from "./download-hook-context";
-export type DownloadSuccessContext = DownloadHookContext & {
-    url: string;
-    expiresIn: number;
-};

package/dist/types/hook-context.d.ts

@@ -1,3 +0,0 @@
-export type HookContext = {
-    request: Request;
-};

package/dist/types/multipart-complete-success-context.d.ts

@@ -1,13 +0,0 @@
-import type { MultipartHookContext } from "./multipart-hook-context";
-export type MultipartCompleteSuccessContext = MultipartHookContext & {
-    uploadId: string;
-    contentLength: number;
-    contentType?: string;
-    eTag?: string;
-    metadata: Record<string, string>;
-    /** Resolved ACL. Omitted when ACL lookup is disabled or unsupported. */
-    acl?: "private" | "public-read";
-    fileName?: string;
-    versionId?: string;
-    lastModified?: string;
-};

package/dist/types/multipart-hook-context.d.ts

@@ -1,7 +0,0 @@
-import type { HookContext } from "./hook-context";
-export type MultipartHookContext = HookContext & {
-    key: string;
-    bucket: string;
-    /** Declared byte size of the file, available during init only. */
-    fileSize?: number;
-};

package/dist/types/multipart-init-success-context.d.ts

@@ -1,8 +0,0 @@
-import type { MultipartHookContext } from "./multipart-hook-context";
-export type MultipartInitSuccessContext = MultipartHookContext & {
-    uploadId: string;
-    contentType?: string;
-    fileSize?: number;
-    metadata?: Record<string, string>;
-    acl?: "private" | "public-read";
-};

package/dist/types/multipart-list-success-context.d.ts

@@ -1,11 +0,0 @@
-import type { HookContext } from "./hook-context";
-export type MultipartListSuccessContext = HookContext & {
-    key: string;
-    bucket: string;
-    uploadId: string;
-    parts: Array<{
-        partNumber: number;
-        size: number;
-        eTag: string;
-    }>;
-};

package/dist/types/upload-complete-context.d.ts

@@ -1,15 +0,0 @@
-import type { HookContext } from "./hook-context";
-/** contentLength and eTag are verified by S3 via HeadObject. */
-export type UploadCompleteContext = HookContext & {
-    key: string;
-    bucket: string;
-    contentType?: string;
-    contentLength: number;
-    eTag?: string;
-    metadata?: Record<string, string>;
-    /** Resolved ACL. Omitted when ACL lookup is disabled or unsupported. */
-    acl?: "private" | "public-read";
-    fileName?: string;
-    versionId?: string;
-    lastModified?: string;
-};

package/dist/types/upload-hook-context.d.ts

@@ -1,10 +0,0 @@
-import type { HookContext } from "./hook-context";
-/** Values are client-declared and not verified by S3. */
-export type UploadHookContext = HookContext & {
-    key: string;
-    bucket: string;
-    contentType?: string;
-    fileSize?: number;
-    metadata?: Record<string, string>;
-    acl?: "private" | "public-read";
-};

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

@@ -1,2 +0,0 @@
-/** HTTP method used for simple (non-multipart) presigned uploads. */
-export type UploadPresignMethod = "POST" | "PUT";

package/dist/types/upload-success-context.d.ts

@@ -1,5 +0,0 @@
-import type { UploadHookContext } from "./upload-hook-context";
-export type UploadSuccessContext = UploadHookContext & {
-    url: string;
-    expiresIn: number;
-};