@constructive-io/s3-utils 2.11.0 → 2.12.1

package/README.md

@@ -12,6 +12,216 @@
    <a href="https://www.npmjs.com/package/@constructive-io/s3-utils"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=uploads%2Fs3-utils%2Fpackage.json"/></a>
 </p>
 
+Unified S3 utilities for the Constructive ecosystem — client factory, file operations, presigned URLs, and bucket management. Built on AWS SDK v3 with support for multiple S3-compatible providers.
+
+## Features
+
+- **Multi-provider support** — AWS S3, MinIO, Cloudflare R2, Google Cloud Storage, DigitalOcean Spaces
+- **Presigned URLs** — generate secure PUT and GET URLs with configurable expiry
+- **File operations** — streaming upload, download, existence checks, and metadata retrieval
+- **Bucket management** — create buckets with provider-appropriate policies and CORS
+- **AWS SDK v3** — modern, modular SDK with tree-shaking support
+
+## Installation
+
+```sh
+npm install @constructive-io/s3-utils
+```
+
+## Quick Start
+
+```typescript
+import {
+  createS3Client,
+  presignPutUrl,
+  presignGetUrl,
+  upload,
+  download,
+} from '@constructive-io/s3-utils';
+
+// 1. Create a client
+const client = createS3Client({
+  provider: 'minio',
+  region: 'us-east-1',
+  endpoint: 'http://minio:9000',
+  accessKeyId: 'minioadmin',
+  secretAccessKey: 'minioadmin',
+});
+
+// 2. Upload a file via stream
+import { createReadStream } from 'fs';
+
+const result = await upload({
+  client,
+  bucket: 'my-bucket',
+  key: 'docs/report.pdf',
+  contentType: 'application/pdf',
+  readStream: createReadStream('/path/to/report.pdf'),
+});
+
+// 3. Generate a presigned download URL
+const url = await presignGetUrl(client, {
+  bucket: 'my-bucket',
+  key: 'docs/report.pdf',
+});
+```
+
+## API
+
+### `createS3Client(config)`
+
+Creates an `S3Client` with provider-specific defaults.
+
+```typescript
+import { createS3Client } from '@constructive-io/s3-utils';
+
+const client = createS3Client({
+  provider: 'r2',
+  region: 'auto',
+  endpoint: 'https://account.r2.cloudflarestorage.com',
+  accessKeyId: 'KEY',
+  secretAccessKey: 'SECRET',
+});
+```
+
+**`StorageConnectionConfig`**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `provider` | `'s3' \| 'minio' \| 'r2' \| 'gcs' \| 'spaces'` | yes | Storage provider |
+| `region` | `string` | yes | S3 region (e.g. `"us-east-1"`) |
+| `endpoint` | `string` | non-AWS | Endpoint URL (required for all providers except `s3`) |
+| `accessKeyId` | `string` | yes | Access key ID |
+| `secretAccessKey` | `string` | yes | Secret access key |
+| `forcePathStyle` | `boolean` | no | Override path-style URL behavior |
+
+Path-style URLs are enabled automatically for `minio`, `r2`, and `gcs`. Virtual-hosted style is used for `s3` and `spaces`.
+
+Throws `S3ConfigError` on invalid configuration.
+
+### `presignPutUrl(client, options)`
+
+Generates a presigned PUT URL for uploading. The URL is locked to the specified key, content type, and content length.
+
+```typescript
+const url = await presignPutUrl(client, {
+  bucket: 'my-bucket',
+  key: 'uploads/photo.jpg',
+  contentType: 'image/jpeg',
+  contentLength: 102400,
+  expiresIn: 900, // default: 900 (15 min)
+});
+```
+
+### `presignGetUrl(client, options)`
+
+Generates a presigned GET URL for downloading. Supports an optional `filename` for `Content-Disposition`.
+
+```typescript
+const url = await presignGetUrl(client, {
+  bucket: 'my-bucket',
+  key: 'uploads/photo.jpg',
+  expiresIn: 3600, // default: 3600 (1 hour)
+  filename: 'photo.jpg', // optional, triggers download prompt
+});
+```
+
+### `headObject(client, bucket, key)`
+
+Checks if an object exists and returns its metadata. Returns `null` if the object is not found.
+
+```typescript
+const meta = await headObject(client, 'my-bucket', 'uploads/photo.jpg');
+// { contentType: 'image/jpeg', contentLength: 102400 } or null
+```
+
+### `fileExists({ client, bucket, key })`
+
+Returns `true` if the object exists, `false` otherwise.
+
+```typescript
+const exists = await fileExists({ client, bucket: 'my-bucket', key: 'doc.pdf' });
+```
+
+### `upload({ client, bucket, key, readStream, contentType })`
+
+Streams a file to S3 using multipart upload.
+
+```typescript
+import { createReadStream } from 'fs';
+
+const result = await upload({
+  client,
+  bucket: 'my-bucket',
+  key: 'uploads/video.mp4',
+  contentType: 'video/mp4',
+  readStream: createReadStream('/path/to/video.mp4'),
+});
+// { Location, ETag, Bucket, Key }
+```
+
+### `download({ client, bucket, key, writeStream })`
+
+Downloads an object from S3 and pipes it to a writable stream.
+
+```typescript
+import { createWriteStream } from 'fs';
+
+await download({
+  client,
+  bucket: 'my-bucket',
+  key: 'uploads/video.mp4',
+  writeStream: createWriteStream('/tmp/video.mp4'),
+});
+```
+
+### `uploadThrough({ client, bucket, key, contentType })`
+
+Returns a `PassThrough` stream that uploads to S3 as data is written. Emits an `'upload'` event with the result when complete.
+
+```typescript
+const pass = uploadThrough({
+  client,
+  bucket: 'my-bucket',
+  key: 'stream-data.csv',
+  contentType: 'text/csv',
+});
+
+pass.on('upload', (result) => {
+  console.log('Upload complete:', result.Location);
+});
+
+someReadable.pipe(pass);
+```
+
+### `createS3Bucket(client, bucket, options)`
+
+Creates a bucket with provider-appropriate policies and CORS configuration.
+
+- **MinIO**: read-only public access policy (list + get)
+- **S3/GCS**: full-access policy with CORS rules for browser uploads
+
+```typescript
+const { success } = await createS3Bucket(client, 'my-bucket', {
+  provider: 'minio',
+});
+```
+
+Returns `{ success: true }` if the bucket was created or already exists.
+
+## Related Packages
+
+| Package | Description |
+|---|---|
+| [`@constructive-io/s3-streamer`](../s3-streamer) | Streaming uploads with automatic content-type detection and metadata extraction |
+| [`@constructive-io/etag-stream`](../etag-stream) | ETag generation from streams |
+| [`@constructive-io/content-type-stream`](../content-type-stream) | Magic-byte content-type detection |
+| [`@constructive-io/uuid-hash`](../uuid-hash) | Deterministic UUID generation from file content |
+
+## License
+
+MIT
+
 ---
 
 ## Education and Tutorials

package/client.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Unified S3 client factory.
+ *
+ * Provides a single, canonical way to create an S3Client across the
+ * Constructive ecosystem. Consumers import from @constructive-io/s3-utils
+ * instead of wiring up @aws-sdk/client-s3 directly.
+ *
+ * Handles provider-specific defaults:
+ * - minio: forces path-style URLs, requires endpoint
+ * - r2: forces path-style URLs, requires endpoint
+ * - gcs: forces path-style URLs, requires endpoint
+ * - s3: virtual-hosted style (AWS default)
+ * - spaces: virtual-hosted style (DigitalOcean default)
+ *
+ * @example
+ * ```typescript
+ * import { createS3Client } from '@constructive-io/s3-utils';
+ *
+ * const client = createS3Client({
+ *   provider: 'minio',
+ *   region: 'us-east-1',
+ *   endpoint: 'http://minio:9000',
+ *   accessKeyId: 'minioadmin',
+ *   secretAccessKey: 'minioadmin',
+ * });
+ * ```
+ */
+import { S3Client } from '@aws-sdk/client-s3';
+/**
+ * Supported storage provider identifiers.
+ *
+ * Used to select provider-specific behavior (e.g., path-style URLs for MinIO,
+ * jurisdiction headers for R2).
+ */
+export type StorageProvider = 's3' | 'minio' | 'r2' | 'gcs' | 'spaces';
+/**
+ * Connection configuration for an S3-compatible storage backend.
+ *
+ * This is the input you provide to connect to your storage provider.
+ * For AWS S3, only `region` and credentials are needed.
+ * For MinIO/R2/etc., also provide `endpoint`.
+ */
+export interface StorageConnectionConfig {
+    /** Storage provider type */
+    provider: StorageProvider;
+    /** S3 region (e.g., "us-east-1"). Required for AWS S3. */
+    region: string;
+    /** S3-compatible endpoint URL (e.g., "http://minio:9000"). Required for non-AWS providers. */
+    endpoint?: string;
+    /** AWS access key ID */
+    accessKeyId: string;
+    /** AWS secret access key */
+    secretAccessKey: string;
+    /** Use path-style URLs (required for MinIO, optional for others) */
+    forcePathStyle?: boolean;
+}
+/**
+ * Structured error for S3 client configuration issues.
+ */
+export declare class S3ConfigError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Create an S3Client from a storage connection config.
+ *
+ * Provider-specific defaults:
+ * - `minio`: forces path-style URLs (required by MinIO)
+ * - `r2`: forces path-style URLs (required by Cloudflare R2)
+ * - `s3`: uses virtual-hosted style (AWS default)
+ * - `gcs`: forces path-style URLs (GCS S3-compatible API)
+ * - `spaces`: uses virtual-hosted style (DigitalOcean default)
+ */
+export declare function createS3Client(config: StorageConnectionConfig): S3Client;

package/client.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * Unified S3 client factory.
+ *
+ * Provides a single, canonical way to create an S3Client across the
+ * Constructive ecosystem. Consumers import from @constructive-io/s3-utils
+ * instead of wiring up @aws-sdk/client-s3 directly.
+ *
+ * Handles provider-specific defaults:
+ * - minio: forces path-style URLs, requires endpoint
+ * - r2: forces path-style URLs, requires endpoint
+ * - gcs: forces path-style URLs, requires endpoint
+ * - s3: virtual-hosted style (AWS default)
+ * - spaces: virtual-hosted style (DigitalOcean default)
+ *
+ * @example
+ * ```typescript
+ * import { createS3Client } from '@constructive-io/s3-utils';
+ *
+ * const client = createS3Client({
+ *   provider: 'minio',
+ *   region: 'us-east-1',
+ *   endpoint: 'http://minio:9000',
+ *   accessKeyId: 'minioadmin',
+ *   secretAccessKey: 'minioadmin',
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.S3ConfigError = void 0;
+exports.createS3Client = createS3Client;
+const client_s3_1 = require("@aws-sdk/client-s3");
+// --- Error ---
+/**
+ * Structured error for S3 client configuration issues.
+ */
+class S3ConfigError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'S3ConfigError';
+        this.code = code;
+    }
+}
+exports.S3ConfigError = S3ConfigError;
+// --- Factory ---
+/**
+ * Create an S3Client from a storage connection config.
+ *
+ * Provider-specific defaults:
+ * - `minio`: forces path-style URLs (required by MinIO)
+ * - `r2`: forces path-style URLs (required by Cloudflare R2)
+ * - `s3`: uses virtual-hosted style (AWS default)
+ * - `gcs`: forces path-style URLs (GCS S3-compatible API)
+ * - `spaces`: uses virtual-hosted style (DigitalOcean default)
+ */
+function createS3Client(config) {
+    if (!config.accessKeyId || !config.secretAccessKey) {
+        throw new S3ConfigError('INVALID_CONFIG', 'accessKeyId and secretAccessKey are required');
+    }
+    if (!config.region) {
+        throw new S3ConfigError('INVALID_CONFIG', 'region is required');
+    }
+    // Providers that require path-style URLs
+    const pathStyleProviders = new Set(['minio', 'r2', 'gcs']);
+    const forcePathStyle = config.forcePathStyle ?? pathStyleProviders.has(config.provider);
+    // Non-AWS providers require an endpoint
+    if (config.provider !== 's3' && !config.endpoint) {
+        throw new S3ConfigError('INVALID_CONFIG', `endpoint is required for provider '${config.provider}'`);
+    }
+    return new client_s3_1.S3Client({
+        region: config.region,
+        endpoint: config.endpoint,
+        forcePathStyle,
+        credentials: {
+            accessKeyId: config.accessKeyId,
+            secretAccessKey: config.secretAccessKey,
+        },
+    });
+}

package/esm/client.js

@@ -0,0 +1,75 @@
+/**
+ * Unified S3 client factory.
+ *
+ * Provides a single, canonical way to create an S3Client across the
+ * Constructive ecosystem. Consumers import from @constructive-io/s3-utils
+ * instead of wiring up @aws-sdk/client-s3 directly.
+ *
+ * Handles provider-specific defaults:
+ * - minio: forces path-style URLs, requires endpoint
+ * - r2: forces path-style URLs, requires endpoint
+ * - gcs: forces path-style URLs, requires endpoint
+ * - s3: virtual-hosted style (AWS default)
+ * - spaces: virtual-hosted style (DigitalOcean default)
+ *
+ * @example
+ * ```typescript
+ * import { createS3Client } from '@constructive-io/s3-utils';
+ *
+ * const client = createS3Client({
+ *   provider: 'minio',
+ *   region: 'us-east-1',
+ *   endpoint: 'http://minio:9000',
+ *   accessKeyId: 'minioadmin',
+ *   secretAccessKey: 'minioadmin',
+ * });
+ * ```
+ */
+import { S3Client } from '@aws-sdk/client-s3';
+// --- Error ---
+/**
+ * Structured error for S3 client configuration issues.
+ */
+export class S3ConfigError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'S3ConfigError';
+        this.code = code;
+    }
+}
+// --- Factory ---
+/**
+ * Create an S3Client from a storage connection config.
+ *
+ * Provider-specific defaults:
+ * - `minio`: forces path-style URLs (required by MinIO)
+ * - `r2`: forces path-style URLs (required by Cloudflare R2)
+ * - `s3`: uses virtual-hosted style (AWS default)
+ * - `gcs`: forces path-style URLs (GCS S3-compatible API)
+ * - `spaces`: uses virtual-hosted style (DigitalOcean default)
+ */
+export function createS3Client(config) {
+    if (!config.accessKeyId || !config.secretAccessKey) {
+        throw new S3ConfigError('INVALID_CONFIG', 'accessKeyId and secretAccessKey are required');
+    }
+    if (!config.region) {
+        throw new S3ConfigError('INVALID_CONFIG', 'region is required');
+    }
+    // Providers that require path-style URLs
+    const pathStyleProviders = new Set(['minio', 'r2', 'gcs']);
+    const forcePathStyle = config.forcePathStyle ?? pathStyleProviders.has(config.provider);
+    // Non-AWS providers require an endpoint
+    if (config.provider !== 's3' && !config.endpoint) {
+        throw new S3ConfigError('INVALID_CONFIG', `endpoint is required for provider '${config.provider}'`);
+    }
+    return new S3Client({
+        region: config.region,
+        endpoint: config.endpoint,
+        forcePathStyle,
+        credentials: {
+            accessKeyId: config.accessKeyId,
+            secretAccessKey: config.secretAccessKey,
+        },
+    });
+}

package/esm/index.js

@@ -1,2 +1,4 @@
+export * from './client';
 export * from './policies';
+export * from './presigned';
 export * from './utils';

package/esm/presigned.js

@@ -0,0 +1,84 @@
+/**
+ * Presigned URL helpers.
+ *
+ * Generates presigned PUT and GET URLs for S3-compatible storage.
+ * Consumers import from @constructive-io/s3-utils instead of wiring
+ * up @aws-sdk/s3-request-presigner directly.
+ *
+ * @example
+ * ```typescript
+ * import { createS3Client, presignGetUrl, presignPutUrl } from '@constructive-io/s3-utils';
+ *
+ * const client = createS3Client({ ... });
+ *
+ * const putUrl = await presignPutUrl(client, {
+ *   bucket: 'my-bucket',
+ *   key: 'uploads/photo.jpg',
+ *   contentType: 'image/jpeg',
+ *   contentLength: 102400,
+ * });
+ *
+ * const getUrl = await presignGetUrl(client, {
+ *   bucket: 'my-bucket',
+ *   key: 'uploads/photo.jpg',
+ * });
+ * ```
+ */
+import { PutObjectCommand, GetObjectCommand, HeadObjectCommand, } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+// --- Functions ---
+/**
+ * Generate a presigned PUT URL for uploading a file to S3.
+ *
+ * The presigned URL is locked to the specific key, content-type, and
+ * content-length via the signature. The client MUST use these exact values
+ * when performing the PUT request.
+ */
+export async function presignPutUrl(client, options) {
+    const { bucket, key, contentType, contentLength, expiresIn = 900 } = options;
+    const command = new PutObjectCommand({
+        Bucket: bucket,
+        Key: key,
+        ContentType: contentType,
+        ContentLength: contentLength,
+    });
+    return getSignedUrl(client, command, { expiresIn });
+}
+/**
+ * Generate a presigned GET URL for downloading a file from S3.
+ *
+ * Used for private files that shouldn't be served through a public CDN.
+ */
+export async function presignGetUrl(client, options) {
+    const { bucket, key, expiresIn = 3600, filename } = options;
+    const params = {
+        Bucket: bucket,
+        Key: key,
+    };
+    if (filename) {
+        const sanitized = filename.replace(/["\\\r\n]/g, '_');
+        params.ResponseContentDisposition = `attachment; filename="${sanitized}"`;
+    }
+    const command = new GetObjectCommand(params);
+    return getSignedUrl(client, command, { expiresIn });
+}
+/**
+ * Check if an object exists in S3 and return its metadata.
+ *
+ * Returns null if the object does not exist.
+ */
+export async function headObject(client, bucket, key) {
+    try {
+        const response = await client.send(new HeadObjectCommand({ Bucket: bucket, Key: key }));
+        return {
+            contentType: response.ContentType,
+            contentLength: response.ContentLength,
+        };
+    }
+    catch (e) {
+        if (e.name === 'NotFound' || e.$metadata?.httpStatusCode === 404) {
+            return null;
+        }
+        throw e;
+    }
+}

package/index.d.ts

@@ -1,2 +1,4 @@
+export * from './client';
 export * from './policies';
+export * from './presigned';
 export * from './utils';

package/index.js

@@ -14,5 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./client"), exports);
 __exportStar(require("./policies"), exports);
+__exportStar(require("./presigned"), exports);
 __exportStar(require("./utils"), exports);

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@constructive-io/s3-utils",
-  "version": "2.11.0",
+  "version": "2.12.1",
   "author": "Constructive <developers@constructive.io>",
-  "description": "s3 utils",
+  "description": "Unified S3 utilities — client factory, file operations, presigned URLs",
   "main": "index.js",
   "module": "esm/index.js",
   "types": "index.d.ts",
@@ -31,11 +31,12 @@
   "keywords": [],
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1009.0",
-    "@aws-sdk/lib-storage": "^3.1009.0"
+    "@aws-sdk/lib-storage": "^3.1009.0",
+    "@aws-sdk/s3-request-presigner": "^3.1009.0"
   },
   "devDependencies": {
     "@types/node": "^22.19.11",
     "makage": "^0.3.0"
   },
-  "gitHead": "1b3af3c5189b9ca2e765b9239a4b287099e64a03"
+  "gitHead": "a8ccaed4f3a7c6c82495241ee1581700db9dd2dd"
 }

package/presigned.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Presigned URL helpers.
+ *
+ * Generates presigned PUT and GET URLs for S3-compatible storage.
+ * Consumers import from @constructive-io/s3-utils instead of wiring
+ * up @aws-sdk/s3-request-presigner directly.
+ *
+ * @example
+ * ```typescript
+ * import { createS3Client, presignGetUrl, presignPutUrl } from '@constructive-io/s3-utils';
+ *
+ * const client = createS3Client({ ... });
+ *
+ * const putUrl = await presignPutUrl(client, {
+ *   bucket: 'my-bucket',
+ *   key: 'uploads/photo.jpg',
+ *   contentType: 'image/jpeg',
+ *   contentLength: 102400,
+ * });
+ *
+ * const getUrl = await presignGetUrl(client, {
+ *   bucket: 'my-bucket',
+ *   key: 'uploads/photo.jpg',
+ * });
+ * ```
+ */
+import type { S3Client } from '@aws-sdk/client-s3';
+export interface PresignPutOptions {
+    /** S3 bucket name */
+    bucket: string;
+    /** S3 object key */
+    key: string;
+    /** MIME type (locked into the signature) */
+    contentType: string;
+    /** File size in bytes (locked into the signature) */
+    contentLength: number;
+    /** URL expiry in seconds (default: 900 = 15 minutes) */
+    expiresIn?: number;
+}
+export interface PresignGetOptions {
+    /** S3 bucket name */
+    bucket: string;
+    /** S3 object key */
+    key: string;
+    /** URL expiry in seconds (default: 3600 = 1 hour) */
+    expiresIn?: number;
+    /** Optional filename for Content-Disposition header */
+    filename?: string;
+}
+export interface HeadObjectResult {
+    contentType?: string;
+    contentLength?: number;
+}
+/**
+ * Generate a presigned PUT URL for uploading a file to S3.
+ *
+ * The presigned URL is locked to the specific key, content-type, and
+ * content-length via the signature. The client MUST use these exact values
+ * when performing the PUT request.
+ */
+export declare function presignPutUrl(client: S3Client, options: PresignPutOptions): Promise<string>;
+/**
+ * Generate a presigned GET URL for downloading a file from S3.
+ *
+ * Used for private files that shouldn't be served through a public CDN.
+ */
+export declare function presignGetUrl(client: S3Client, options: PresignGetOptions): Promise<string>;
+/**
+ * Check if an object exists in S3 and return its metadata.
+ *
+ * Returns null if the object does not exist.
+ */
+export declare function headObject(client: S3Client, bucket: string, key: string): Promise<HeadObjectResult | null>;

package/presigned.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Presigned URL helpers.
+ *
+ * Generates presigned PUT and GET URLs for S3-compatible storage.
+ * Consumers import from @constructive-io/s3-utils instead of wiring
+ * up @aws-sdk/s3-request-presigner directly.
+ *
+ * @example
+ * ```typescript
+ * import { createS3Client, presignGetUrl, presignPutUrl } from '@constructive-io/s3-utils';
+ *
+ * const client = createS3Client({ ... });
+ *
+ * const putUrl = await presignPutUrl(client, {
+ *   bucket: 'my-bucket',
+ *   key: 'uploads/photo.jpg',
+ *   contentType: 'image/jpeg',
+ *   contentLength: 102400,
+ * });
+ *
+ * const getUrl = await presignGetUrl(client, {
+ *   bucket: 'my-bucket',
+ *   key: 'uploads/photo.jpg',
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.presignPutUrl = presignPutUrl;
+exports.presignGetUrl = presignGetUrl;
+exports.headObject = headObject;
+const client_s3_1 = require("@aws-sdk/client-s3");
+const s3_request_presigner_1 = require("@aws-sdk/s3-request-presigner");
+// --- Functions ---
+/**
+ * Generate a presigned PUT URL for uploading a file to S3.
+ *
+ * The presigned URL is locked to the specific key, content-type, and
+ * content-length via the signature. The client MUST use these exact values
+ * when performing the PUT request.
+ */
+async function presignPutUrl(client, options) {
+    const { bucket, key, contentType, contentLength, expiresIn = 900 } = options;
+    const command = new client_s3_1.PutObjectCommand({
+        Bucket: bucket,
+        Key: key,
+        ContentType: contentType,
+        ContentLength: contentLength,
+    });
+    return (0, s3_request_presigner_1.getSignedUrl)(client, command, { expiresIn });
+}
+/**
+ * Generate a presigned GET URL for downloading a file from S3.
+ *
+ * Used for private files that shouldn't be served through a public CDN.
+ */
+async function presignGetUrl(client, options) {
+    const { bucket, key, expiresIn = 3600, filename } = options;
+    const params = {
+        Bucket: bucket,
+        Key: key,
+    };
+    if (filename) {
+        const sanitized = filename.replace(/["\\\r\n]/g, '_');
+        params.ResponseContentDisposition = `attachment; filename="${sanitized}"`;
+    }
+    const command = new client_s3_1.GetObjectCommand(params);
+    return (0, s3_request_presigner_1.getSignedUrl)(client, command, { expiresIn });
+}
+/**
+ * Check if an object exists in S3 and return its metadata.
+ *
+ * Returns null if the object does not exist.
+ */
+async function headObject(client, bucket, key) {
+    try {
+        const response = await client.send(new client_s3_1.HeadObjectCommand({ Bucket: bucket, Key: key }));
+        return {
+            contentType: response.ContentType,
+            contentLength: response.ContentLength,
+        };
+    }
+    catch (e) {
+        if (e.name === 'NotFound' || e.$metadata?.httpStatusCode === 404) {
+            return null;
+        }
+        throw e;
+    }
+}