@byline/storage-s3 1.2.1 → 1.3.0

package/dist/index.d.ts

@@ -6,4 +6,4 @@
  * Copyright (c) Infonomic Company Limited
  */
 export { s3StorageProvider } from './s3-storage-provider.js';
-export type { S3StorageConfig } from './s3-storage-provider.js';
+export type { S3MetadataSupplier, S3StorageConfig } from './s3-storage-provider.js';

package/dist/s3-storage-provider.d.ts

@@ -5,7 +5,15 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { IStorageProvider } from '@byline/core';
+import { type ObjectCannedACL, type S3ClientConfig } from '@aws-sdk/client-s3';
+import type { IStorageProvider, UploadFileOptions } from '@byline/core';
+/**
+ * Per-upload S3 metadata supplier. Receives the same `UploadFileOptions`
+ * passed to `storage.upload()` so callers can derive metadata from the
+ * collection / filename / mime type / target path. Return value is
+ * forwarded as S3 user-metadata (`x-amz-meta-*` headers).
+ */
+export type S3MetadataSupplier = Record<string, string> | ((options: UploadFileOptions) => Record<string, string> | undefined);
 export interface S3StorageConfig {
     /** S3 bucket name. */
     bucket: string;
@@ -14,10 +22,26 @@ export interface S3StorageConfig {
      * For region-agnostic providers (e.g. Cloudflare R2) use `'auto'`.
      */
     region: string;
-    /** AWS Access Key ID (or equivalent credential for compatible providers). */
-    accessKeyId: string;
-    /** AWS Secret Access Key (or equivalent credential for compatible providers). */
-    secretAccessKey: string;
+    /**
+     * AWS Access Key ID (or equivalent credential for compatible providers).
+     *
+     * Optional — when omitted (along with `secretAccessKey`), the AWS SDK
+     * resolves credentials via its default provider chain (IAM role / instance
+     * profile, SSO, environment variables, `~/.aws/credentials`, etc.). This
+     * is the recommended path for production AWS deployments.
+     */
+    accessKeyId?: string;
+    /**
+     * AWS Secret Access Key (or equivalent credential for compatible providers).
+     * Must be set together with `accessKeyId`. See `accessKeyId` for the
+     * default-credential-chain fallback.
+     */
+    secretAccessKey?: string;
+    /**
+     * Optional session token, for temporary credentials issued by STS / SSO.
+     * Only meaningful when `accessKeyId` and `secretAccessKey` are also set.
+     */
+    sessionToken?: string;
     /**
      * Custom endpoint for S3-compatible providers.
      *
@@ -45,9 +69,50 @@ export interface S3StorageConfig {
      * Optional key prefix (folder) prepended to all object keys inside the
      * bucket. No leading slash; trailing slash is added automatically.
      *
+     * Ignored when `UploadFileOptions.targetStoragePath` is set — variant
+     * uploads compute their key from the original's `storagePath`, which
+     * already carries the prefix.
+     *
      * @example `'byline'` → keys stored as `byline/<collection>/<year>/...`
      */
     pathPrefix?: string;
+    /**
+     * S3 canned ACL applied to every uploaded object.
+     *
+     * Many modern S3 setups (AWS S3 Block-Public-Access, Cloudflare R2) reject
+     * ACL headers entirely — leave this unset on those buckets and grant
+     * read access via bucket policy instead.
+     *
+     * @example `'public-read'` — legacy public-read bucket
+     */
+    acl?: ObjectCannedACL;
+    /**
+     * Default `Cache-Control` header written to every uploaded object's
+     * metadata, used by S3/CDNs when serving the file. Long-lived
+     * immutable URLs are common for content with UUID-prefixed keys.
+     *
+     * @example `'public, max-age=31536000, immutable'`
+     */
+    cacheControl?: string;
+    /**
+     * Static or per-upload S3 user-metadata. Static keys are merged with the
+     * per-upload result if both are provided; per-upload values win on key
+     * collision.
+     *
+     * Keys must be ASCII; values are quoted by the SDK as needed. Each entry
+     * is sent as an `x-amz-meta-<key>` header.
+     *
+     * @example `{ uploader: 'byline-cms' }`
+     */
+    metadata?: S3MetadataSupplier;
+    /**
+     * Escape hatch for advanced S3 client tuning — `requestHandler`,
+     * `maxAttempts`, `retryMode`, custom `httpAgent`, `useArnRegion`, etc.
+     * Merged into the underlying `S3Client` config; explicit named fields
+     * on `S3StorageConfig` (`region`, `endpoint`, `forcePathStyle`,
+     * credentials) take precedence on key collision.
+     */
+    clientConfig?: Partial<S3ClientConfig>;
 }
 /**
  * Create an S3-compatible storage provider.
@@ -59,7 +124,11 @@ export interface S3StorageConfig {
  * Uploaded files are stored at:
  *   `[pathPrefix/]<collection>/<year>/<month>/<uuid>-<filename>`
  *
- * @example AWS S3
+ * Image variants (thumbnail / card / etc.) are written as siblings of the
+ * original under the same prefix, e.g.:
+ *   `<...>-<filename>-<variantName>.<format>`
+ *
+ * @example AWS S3 with explicit keys
  * ```ts
  * import { s3StorageProvider } from '@byline/storage-s3'
  *
@@ -69,6 +138,17 @@ export interface S3StorageConfig {
  *   accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
  *   secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  *   publicUrl: 'https://cdn.example.com',
+ *   cacheControl: 'public, max-age=31536000, immutable',
+ * })
+ * ```
+ *
+ * @example AWS S3 with the default credential chain (IAM role / SSO / env)
+ * ```ts
+ * storage: s3StorageProvider({
+ *   bucket: 'my-cms-bucket',
+ *   region: 'eu-west-1',
+ *   // accessKeyId / secretAccessKey omitted — the AWS SDK resolves
+ *   // credentials via its default provider chain.
  * })
  * ```
  *
@@ -96,5 +176,15 @@ export interface S3StorageConfig {
  *   publicUrl: 'http://localhost:9000/byline',
  * })
  * ```
+ *
+ * @example Per-upload metadata + retry tuning
+ * ```ts
+ * storage: s3StorageProvider({
+ *   bucket: 'my-cms-bucket',
+ *   region: 'eu-west-1',
+ *   metadata: (opts) => ({ collection: opts.collection ?? 'uploads' }),
+ *   clientConfig: { maxAttempts: 5, retryMode: 'adaptive' },
+ * })
+ * ```
  */
 export declare function s3StorageProvider(config: S3StorageConfig): IStorageProvider;

package/dist/s3-storage-provider.js

@@ -7,7 +7,7 @@
  */
 import path from 'node:path';
 import { Readable } from 'node:stream';
-import { DeleteObjectCommand, S3Client } from '@aws-sdk/client-s3';
+import { DeleteObjectCommand, S3Client, } from '@aws-sdk/client-s3';
 import { Upload } from '@aws-sdk/lib-storage';
 import { v4 as uuidv4 } from 'uuid';
 // ---------------------------------------------------------------------------
@@ -40,6 +40,15 @@ function toReadable(stream) {
     // NodeJS.ReadableStream is structurally compatible with Readable.
     return stream;
 }
+function resolveMetadata(supplier, options) {
+    if (!supplier)
+        return undefined;
+    if (typeof supplier === 'function') {
+        const value = supplier(options);
+        return value && Object.keys(value).length > 0 ? value : undefined;
+    }
+    return Object.keys(supplier).length > 0 ? supplier : undefined;
+}
 // ---------------------------------------------------------------------------
 // Provider implementation
 // ---------------------------------------------------------------------------
@@ -49,25 +58,42 @@ class S3StorageProvider {
     bucket;
     publicUrl;
     pathPrefix;
+    acl;
+    cacheControl;
+    metadata;
     constructor(config) {
-        this.client = new S3Client({
-            region: config.region,
-            credentials: {
+        // Pass an explicit `credentials` block only when both halves of a
+        // long-lived key pair are present. Otherwise leave it absent so the
+        // SDK falls back to its default credential provider chain (IAM role,
+        // SSO, env, ~/.aws/credentials).
+        const explicitCredentials = config.accessKeyId && config.secretAccessKey
+            ? {
                 accessKeyId: config.accessKeyId,
                 secretAccessKey: config.secretAccessKey,
-            },
+                ...(config.sessionToken ? { sessionToken: config.sessionToken } : {}),
+            }
+            : undefined;
+        this.client = new S3Client({
+            ...config.clientConfig,
+            region: config.region,
+            ...(explicitCredentials ? { credentials: explicitCredentials } : {}),
             ...(config.endpoint ? { endpoint: config.endpoint } : {}),
             ...(config.forcePathStyle ? { forcePathStyle: true } : {}),
         });
         this.bucket = config.bucket;
         this.pathPrefix = config.pathPrefix;
+        this.acl = config.acl;
+        this.cacheControl = config.cacheControl;
+        this.metadata = config.metadata;
         // Derive a default public URL if not explicitly provided.
         this.publicUrl =
             config.publicUrl?.replace(/\/$/, '') ??
                 `https://${config.bucket}.s3.${config.region}.amazonaws.com`;
     }
     async upload(stream, options) {
-        const objectKey = buildObjectKey(this.pathPrefix, options.collection, options.filename);
+        const objectKey = options.targetStoragePath ??
+            buildObjectKey(this.pathPrefix, options.collection, options.filename);
+        const userMetadata = resolveMetadata(this.metadata, options);
         const upload = new Upload({
             client: this.client,
             params: {
@@ -76,6 +102,9 @@ class S3StorageProvider {
                 Body: toReadable(stream),
                 ContentType: options.mimeType,
                 ContentLength: options.size,
+                ...(this.acl ? { ACL: this.acl } : {}),
+                ...(this.cacheControl ? { CacheControl: this.cacheControl } : {}),
+                ...(userMetadata ? { Metadata: userMetadata } : {}),
             },
         });
         await upload.done();
@@ -86,6 +115,8 @@ class S3StorageProvider {
         };
     }
     async delete(storagePath) {
+        // S3 DeleteObject is idempotent — succeeds (204) whether the key
+        // exists or not — so no need for a NotFound branch here.
         await this.client.send(new DeleteObjectCommand({
             Bucket: this.bucket,
             Key: storagePath,
@@ -108,7 +139,11 @@ class S3StorageProvider {
  * Uploaded files are stored at:
  *   `[pathPrefix/]<collection>/<year>/<month>/<uuid>-<filename>`
  *
- * @example AWS S3
+ * Image variants (thumbnail / card / etc.) are written as siblings of the
+ * original under the same prefix, e.g.:
+ *   `<...>-<filename>-<variantName>.<format>`
+ *
+ * @example AWS S3 with explicit keys
  * ```ts
  * import { s3StorageProvider } from '@byline/storage-s3'
  *
@@ -118,6 +153,17 @@ class S3StorageProvider {
  *   accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
  *   secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  *   publicUrl: 'https://cdn.example.com',
+ *   cacheControl: 'public, max-age=31536000, immutable',
+ * })
+ * ```
+ *
+ * @example AWS S3 with the default credential chain (IAM role / SSO / env)
+ * ```ts
+ * storage: s3StorageProvider({
+ *   bucket: 'my-cms-bucket',
+ *   region: 'eu-west-1',
+ *   // accessKeyId / secretAccessKey omitted — the AWS SDK resolves
+ *   // credentials via its default provider chain.
  * })
  * ```
  *
@@ -145,6 +191,16 @@ class S3StorageProvider {
  *   publicUrl: 'http://localhost:9000/byline',
  * })
  * ```
+ *
+ * @example Per-upload metadata + retry tuning
+ * ```ts
+ * storage: s3StorageProvider({
+ *   bucket: 'my-cms-bucket',
+ *   region: 'eu-west-1',
+ *   metadata: (opts) => ({ collection: opts.collection ?? 'uploads' }),
+ *   clientConfig: { maxAttempts: 5, retryMode: 'adaptive' },
+ * })
+ * ```
  */
 export function s3StorageProvider(config) {
     return new S3StorageProvider(config);

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/storage-s3",
   "private": false,
   "license": "MPL-2.0",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -43,7 +43,7 @@
     "@aws-sdk/lib-storage": "^3.1041.0",
     "npm-run-all": "^4.1.5",
     "uuid": "^14.0.0",
-    "@byline/core": "1.2.1"
+    "@byline/core": "1.3.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.14",