@better-s3/server 3.1045.2 → 3.1047.0

package/dist/types/s3-handler-config.d.ts

@@ -0,0 +1,66 @@
+import type { S3Client } from "@aws-sdk/client-s3";
+import type { HookContext } from "./hook-context";
+import type { UploadHookContext } from "./upload-hook-context";
+import type { UploadSuccessContext } from "./upload-success-context";
+import type { UploadCompleteContext } from "./upload-complete-context";
+import type { DownloadHookContext } from "./download-hook-context";
+import type { DownloadSuccessContext } from "./download-success-context";
+import type { DeleteHookContext } from "./delete-hook-context";
+import type { MultipartHookContext } from "./multipart-hook-context";
+import type { MultipartInitSuccessContext } from "./multipart-init-success-context";
+import type { MultipartCompleteSuccessContext } from "./multipart-complete-success-context";
+import type { MultipartListSuccessContext } from "./multipart-list-success-context";
+export type S3HandlerConfig = {
+    s3: S3Client;
+    defaultBucket: string;
+    /**
+     * When enabled, confirmation handlers call GetObjectAcl to infer whether
+     * the object is public-read or private.
+     *
+     * Keep disabled unless you explicitly need ACL inference in responses/hooks,
+     * because it adds one extra S3 request per upload confirmation.
+     *
+     * @default false
+     */
+    resolveObjectAcl?: boolean;
+    guard?: (context: HookContext) => Promise<void> | void;
+    upload?: {
+        enabled?: boolean;
+        method?: "post" | "put";
+        requireFileSize?: boolean;
+        presignGuard?: (context: UploadHookContext) => Promise<void> | void;
+        onPresigned?: (context: UploadSuccessContext) => Promise<void> | void;
+        confirmGuard?: (context: HookContext & {
+            key: string;
+            bucket: string;
+        }) => Promise<void> | void;
+        onUploadConfirmed?: (context: UploadCompleteContext) => Promise<void> | void;
+    };
+    download?: {
+        enabled?: boolean;
+        presignGuard?: (context: DownloadHookContext) => Promise<void> | void;
+        onPresigned?: (context: DownloadSuccessContext) => Promise<void> | void;
+    };
+    delete?: {
+        enabled?: boolean;
+        deleteGuard?: (context: DeleteHookContext) => Promise<void> | void;
+        onDeleted?: (context: DeleteHookContext) => Promise<void> | void;
+    };
+    multipart?: {
+        enabled?: boolean;
+        requireFileSize?: boolean;
+        initGuard?: (context: MultipartHookContext) => Promise<void> | void;
+        partGuard?: (context: MultipartHookContext) => Promise<void> | void;
+        completeGuard?: (context: MultipartHookContext) => Promise<void> | void;
+        abortGuard?: (context: MultipartHookContext) => Promise<void> | void;
+        listGuard?: (context: MultipartHookContext & {
+            uploadId: string;
+        }) => Promise<void> | void;
+        onInit?: (context: MultipartInitSuccessContext) => Promise<void> | void;
+        onComplete?: (context: MultipartCompleteSuccessContext) => Promise<void> | void;
+        onAbort?: (context: MultipartHookContext & {
+            uploadId: string;
+        }) => Promise<void> | void;
+        onList?: (context: MultipartListSuccessContext) => Promise<void> | void;
+    };
+};

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

@@ -0,0 +1 @@
+export type S3Handler = (request: Request) => Promise<Response>;

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

@@ -0,0 +1,16 @@
+import type { S3Handler } from "./s3-handler";
+export type S3Handlers = {
+    presign: {
+        upload: S3Handler;
+        confirm: S3Handler;
+        download: S3Handler;
+    };
+    multipart: {
+        init: S3Handler;
+        part: S3Handler;
+        complete: S3Handler;
+        abort: S3Handler;
+        listParts: S3Handler;
+    };
+    delete: S3Handler;
+};

package/dist/types/s3-route-handler-config.d.ts

@@ -0,0 +1,4 @@
+import type { S3HandlerConfig } from "./s3-handler-config";
+export type S3RouteHandlerConfig = S3HandlerConfig & {
+    basePath: string;
+};

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

@@ -0,0 +1,15 @@
+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

@@ -0,0 +1,10 @@
+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-success-context.d.ts

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

package/dist/types.d.ts

@@ -1,214 +1 @@
-import type { S3Client } from "@aws-sdk/client-s3";
-export type HookContext = {
-    request: Request;
-};
-/** Values are **client-declared** — not verified by S3. */
-export type UploadHookContext = HookContext & {
-    key: string;
-    bucket: string;
-    /** Client-declared MIME type. */
-    contentType?: string;
-    /** Client-declared file size in bytes. Can be spoofed — use for pre-checks only. */
-    fileSize?: number;
-    metadata?: Record<string, string>;
-    acl?: "private" | "public-read";
-};
-export type UploadSuccessContext = UploadHookContext & {
-    url: string;
-    expiresIn: number;
-};
-/** `contentLength` and `eTag` are **verified by S3** via `HeadObject`. */
-export type UploadCompleteContext = HookContext & {
-    key: string;
-    bucket: string;
-    /** MIME type from HeadObject. */
-    contentType?: string;
-    /** Verified file size in bytes from HeadObject. */
-    contentLength: number;
-    /** ETag from HeadObject. */
-    eTag?: string;
-    metadata?: Record<string, string>;
-    acl: "private" | "public-read";
-    /** Display file name parsed from the object's Content-Disposition header. */
-    fileName?: string;
-    /** Public URL of the object. Only present when `acl` is `public-read` and `publicUrlBase` is configured. */
-    publicUrl?: 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 DownloadHookContext = HookContext & {
-    key: string;
-    bucket: string;
-    fileName?: string;
-};
-export type DownloadSuccessContext = DownloadHookContext & {
-    url: string;
-    expiresIn: number;
-};
-export type DeleteHookContext = HookContext & {
-    key: string;
-    bucket: string;
-};
-export type MultipartHookContext = HookContext & {
-    key: string;
-    bucket: string;
-    /**
-     * Declared byte size of the file — available during `init` only.
-     * Undefined during `part`, `complete`, and `abort` operations.
-     */
-    fileSize?: number;
-};
-export type MultipartInitSuccessContext = MultipartHookContext & {
-    uploadId: string;
-    contentType?: string;
-    /** Declared byte size of the file (as provided by the client). */
-    fileSize?: number;
-    metadata?: Record<string, string>;
-    acl?: "private" | "public-read";
-};
-export type MultipartCompleteSuccessContext = MultipartHookContext & {
-    uploadId: string;
-    contentLength: number;
-    contentType?: string;
-    eTag?: string;
-    metadata: Record<string, string>;
-    acl: "private" | "public-read";
-    /** Display file name parsed from the object's Content-Disposition header. */
-    fileName?: string;
-    /** Public URL of the object. Only present when `acl` is `public-read` and `publicUrlBase` is configured. */
-    publicUrl?: 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 S3HandlerConfig = {
-    /** The S3 client instance used to communicate with your bucket. */
-    s3: S3Client;
-    /** Default bucket used when no `bucket` is specified in the request payload. */
-    defaultBucket: string;
-    /**
-     * Resolves the public base URL for a bucket. The returned string is combined
-     * with the object key to produce `publicUrl` on upload/multipart responses
-     * when the object ACL is `public-read`. Return `undefined` for unknown buckets
-     * or omit entirely if all objects are private.
-     *
-     * ```ts
-     * // Single bucket (path-style or virtual-hosted)
-     * resolvePublicUrl: (_bucket) => "https://cdn.example.com"
-     *
-     * // Multiple buckets — each mapped to its own domain
-     * resolvePublicUrl: (bucket) =>
-     *   ({ avatars: "https://cdn.example.com", media: "https://media.example.com" })[bucket]
-     * ```
-     */
-    resolvePublicUrl?: (bucket: string) => string | undefined;
-    /**
-     * Runs before every request. Return normally to allow, throw to reject.
-     * Attach `status` to the thrown error to set the HTTP response code (default `403`).
-     */
-    guard?: (context: HookContext) => Promise<void> | void;
-    upload?: {
-        /** Enable the upload endpoints. @default false */
-        enabled?: boolean;
-        /**
-         * Presign method for simple (non-multipart) uploads.
-         * Use `"put"` for S3-compatible providers that do not support presigned POST (e.g. Cloudflare R2).
-         * @default "post"
-         */
-        method?: "post" | "put";
-        /**
-         * Reject presign requests that do not include `fileSize`.
-         *
-         * When `true` and `method` is `"put"`, the handler returns `400` if the
-         * client omits `fileSize`.  This guarantees that every generated presigned
-         * PUT URL has `Content-Length` locked into its HMAC signature — preventing
-         * a caller from uploading a file of a different size with the same URL.
-         *
-         * Has no effect when `method` is `"post"` because presigned POST already
-         * enforces size via the `content-length-range` policy condition.
-         *
-         * @default false
-         */
-        requireFileSize?: boolean;
-        /** Runs before presigned URL generation. Values are **client-declared**. */
-        presignGuard?: (context: UploadHookContext) => Promise<void> | void;
-        /** Fires after presigned URL is issued. File not yet uploaded. */
-        onPresigned?: (context: UploadSuccessContext) => Promise<void> | void;
-        /** Runs before upload confirmation. */
-        confirmGuard?: (context: HookContext & {
-            key: string;
-            bucket: string;
-        }) => Promise<void> | void;
-        /** Fires after upload confirmation. Values are **verified by S3** via `HeadObject`. */
-        onUploadConfirmed?: (context: UploadCompleteContext) => Promise<void> | void;
-    };
-    download?: {
-        /** Enable the download endpoint. @default false */
-        enabled?: boolean;
-        /** Runs before presigned GET URL generation. Values are **client-declared**. */
-        presignGuard?: (context: DownloadHookContext) => Promise<void> | void;
-        /** Fires after presigned GET URL is issued. */
-        onPresigned?: (context: DownloadSuccessContext) => Promise<void> | void;
-    };
-    delete?: {
-        /** Enable the delete endpoint. @default false */
-        enabled?: boolean;
-        /** Runs before object deletion. Values are **client-declared**. */
-        deleteGuard?: (context: DeleteHookContext) => Promise<void> | void;
-        /** Fires after object is successfully deleted. */
-        onDeleted?: (context: DeleteHookContext) => Promise<void> | void;
-    };
-    multipart?: {
-        /** Enable all multipart upload endpoints. @default false */
-        enabled?: boolean;
-        /**
-         * Reject multipart init requests that do not include `fileSize`.
-         *
-         * When `true`, the handler returns `400` if the client omits `fileSize`
-         * on the init call.  Because the react client derives each part's byte
-         * count from `file.size` (which is always known), this transitively
-         * ensures that every `UploadPart` presigned URL has `Content-Length`
-         * locked into its HMAC signature.
-         *
-         * @default false
-         */
-        requireFileSize?: boolean;
-        /** Runs before `CreateMultipartUpload`. Values are **client-declared**. */
-        initGuard?: (context: MultipartHookContext) => Promise<void> | void;
-        /** Runs before `UploadPart` presign. */
-        partGuard?: (context: MultipartHookContext) => Promise<void> | void;
-        /** Runs before `CompleteMultipartUpload`. */
-        completeGuard?: (context: MultipartHookContext) => Promise<void> | void;
-        /** Runs before `AbortMultipartUpload`. */
-        abortGuard?: (context: MultipartHookContext) => Promise<void> | void;
-        /** Fires after `CreateMultipartUpload`. */
-        onInit?: (context: MultipartInitSuccessContext) => Promise<void> | void;
-        /** Fires after `CompleteMultipartUpload`. Values are **verified by S3** via `HeadObject`. */
-        onComplete?: (context: MultipartCompleteSuccessContext) => Promise<void> | void;
-        /** Fires after `AbortMultipartUpload`. */
-        onAbort?: (context: MultipartHookContext & {
-            uploadId: string;
-        }) => Promise<void> | void;
-    };
-};
-export type S3RouteHandlerConfig = S3HandlerConfig & {
-    basePath: string;
-};
-export type S3Handler = (request: Request) => Promise<Response>;
-export type S3Handlers = {
-    presign: {
-        upload: S3Handler;
-        confirm: S3Handler;
-        download: S3Handler;
-    };
-    multipart: {
-        init: S3Handler;
-        part: S3Handler;
-        complete: S3Handler;
-        abort: S3Handler;
-    };
-    delete: S3Handler;
-};
+export * from "./types/index";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-s3/server",
-  "version": "3.1045.2",
+  "version": "3.1047.0",
   "description": "Framework-agnostic S3 server handlers — presigned uploads, downloads, deletes, and multipart operations",
   "keywords": [
     "s3",
@@ -46,17 +46,17 @@
     "dist"
   ],
   "dependencies": {
-    "@aws-sdk/s3-presigned-post": "^3.1045.0",
-    "@aws-sdk/s3-request-presigner": "^3.1045.0"
+    "@aws-sdk/s3-presigned-post": "^3.1055.0",
+    "@aws-sdk/s3-request-presigner": "^3.1055.0"
   },
   "peerDependencies": {
     "@aws-sdk/client-s3": ">=3"
   },
   "devDependencies": {
-    "@aws-sdk/client-s3": "^3.1045.0",
+    "@aws-sdk/client-s3": "^3.1055.0",
     "tsc-alias": "^1.8.17",
     "tsup": "^8.5.1",
-    "typescript": "^6.0.3"
+    "typescript": "6.0.3"
   },
   "publishConfig": {
     "access": "public"

package/dist/helpers/build-public-url.d.ts

@@ -1,13 +0,0 @@
-/**
- * Builds the public URL for an S3 object.
- *
- * Returns `undefined` when:
- * - the object is `"private"`,
- * - `publicUrlBase` is not provided, or
- * - `publicUrlBase` returns `undefined` for the given bucket.
- *
- * @param publicUrlBase - A function that returns the base URL for a given bucket,
- *   or `undefined` when no public URL is available for that bucket.
- *   Matches the `resolvePublicUrl` field of `S3HandlerConfig`.
- */
-export declare function buildPublicUrl(publicUrlBase: ((bucket: string) => string | undefined) | undefined, bucket: string, key: string, acl: "public-read" | "private"): string | undefined;