@constructive-io/s3-utils 2.10.2 → 2.12.0

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.10.2",
+  "version": "2.12.0",
   "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": "baae875effd00af36577612c861d0f6f9a1a792a"
+  "gitHead": "434a578648cb04d3ed25e79a75c654f71573292f"
 }

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;
+    }
+}