@better-media/adapter-storage-s3 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 abenezeratnafu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
+ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# @better-media/adapter-storage-s3
+
+Amazon S3 and S3-compatible storage adapter for the Better Media framework.
+
+## Features
+
+- **S3 Support**: Works with AWS S3, Minio, DigitalOcean Spaces, Cloudflare R2, etc.
+- **Presigned URLs**: Securely upload from or download to the browser without exposing credentials.
+- **Streaming**: Supports high-performance streaming for large media files.
+
+## Usage
+
+```ts
+import { S3StorageAdapter } from "@better-media/adapter-storage-s3";
+
+const storage = new S3StorageAdapter({
+  region: "us-east-1",
+  bucket: "media-bucket",
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+});
+```
+
+See [better-media.dev/docs/adapters/storage-s3](https://better-media.dev/docs/adapters/storage-s3) for more details.

package/dist/index.d.mts

@@ -0,0 +1,57 @@
+import { StorageAdapter, GetUrlOptions, PresignedUploadOptions, PresignedUploadResult } from '@better-media/core';
+
+interface S3StorageConfig {
+    /** AWS region (e.g. "us-east-1") */
+    region: string;
+    /** S3 bucket name. Can be a string, or a resolver function that determines the bucket based on the key. */
+    bucket: string | ((key: string) => string);
+    /** AWS access key ID */
+    accessKeyId: string;
+    /** AWS secret access key */
+    secretAccessKey: string;
+    /**
+     * Custom endpoint for S3-compatible storage (e.g. MinIO).
+     * Omit for standard AWS S3.
+     */
+    endpoint?: string;
+    /**
+     * Use path-style bucket URLs (bucket.endpoint vs endpoint/bucket).
+     * Required for MinIO and some S3-compatible services.
+     */
+    forcePathStyle?: boolean;
+}
+
+/**
+ * S3 storage adapter for production deployments.
+ * Supports AWS S3 and S3-compatible object storage (MinIO, etc.).
+ */
+declare class S3StorageAdapter implements StorageAdapter {
+    private readonly client;
+    private readonly bucketResolver;
+    constructor(config: S3StorageConfig);
+    private isNotFoundError;
+    private getBucket;
+    get(key: string): Promise<Buffer | null>;
+    put(key: string, value: Buffer): Promise<void>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    getSize(key: string): Promise<number | null>;
+    getStream(key: string): Promise<ReadableStream<Uint8Array> | null>;
+    getUrl(key: string, options?: GetUrlOptions): Promise<string>;
+    /**
+     * Create a presigned upload for direct-to-storage upload.
+     *
+     * - **POST**: Uses an S3 Policy to strictly enforce `Content-Type` and
+     *   `content-length-range` server-side. S3 rejects any upload violating these.
+     *   Best for web/browser clients using multipart forms.
+     *
+     * - **PUT**: Signs `ContentType`, `ContentLength`, and metadata headers into the URL.
+     *   S3 rejects any request that presents mismatched header values.
+     *   Best for mobile/API clients doing direct binary body uploads.
+     */
+    createPresignedUpload(key: string, options: PresignedUploadOptions): Promise<PresignedUploadResult>;
+    private _createPresignedPost;
+    private _createPresignedPut;
+}
+
+export { S3StorageAdapter, type S3StorageConfig };

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+import { StorageAdapter, GetUrlOptions, PresignedUploadOptions, PresignedUploadResult } from '@better-media/core';
+
+interface S3StorageConfig {
+    /** AWS region (e.g. "us-east-1") */
+    region: string;
+    /** S3 bucket name. Can be a string, or a resolver function that determines the bucket based on the key. */
+    bucket: string | ((key: string) => string);
+    /** AWS access key ID */
+    accessKeyId: string;
+    /** AWS secret access key */
+    secretAccessKey: string;
+    /**
+     * Custom endpoint for S3-compatible storage (e.g. MinIO).
+     * Omit for standard AWS S3.
+     */
+    endpoint?: string;
+    /**
+     * Use path-style bucket URLs (bucket.endpoint vs endpoint/bucket).
+     * Required for MinIO and some S3-compatible services.
+     */
+    forcePathStyle?: boolean;
+}
+
+/**
+ * S3 storage adapter for production deployments.
+ * Supports AWS S3 and S3-compatible object storage (MinIO, etc.).
+ */
+declare class S3StorageAdapter implements StorageAdapter {
+    private readonly client;
+    private readonly bucketResolver;
+    constructor(config: S3StorageConfig);
+    private isNotFoundError;
+    private getBucket;
+    get(key: string): Promise<Buffer | null>;
+    put(key: string, value: Buffer): Promise<void>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    getSize(key: string): Promise<number | null>;
+    getStream(key: string): Promise<ReadableStream<Uint8Array> | null>;
+    getUrl(key: string, options?: GetUrlOptions): Promise<string>;
+    /**
+     * Create a presigned upload for direct-to-storage upload.
+     *
+     * - **POST**: Uses an S3 Policy to strictly enforce `Content-Type` and
+     *   `content-length-range` server-side. S3 rejects any upload violating these.
+     *   Best for web/browser clients using multipart forms.
+     *
+     * - **PUT**: Signs `ContentType`, `ContentLength`, and metadata headers into the URL.
+     *   S3 rejects any request that presents mismatched header values.
+     *   Best for mobile/API clients doing direct binary body uploads.
+     */
+    createPresignedUpload(key: string, options: PresignedUploadOptions): Promise<PresignedUploadResult>;
+    private _createPresignedPost;
+    private _createPresignedPut;
+}
+
+export { S3StorageAdapter, type S3StorageConfig };

package/dist/index.js

@@ -0,0 +1,225 @@
+'use strict';
+
+var clientS3 = require('@aws-sdk/client-s3');
+var s3RequestPresigner = require('@aws-sdk/s3-request-presigner');
+var s3PresignedPost = require('@aws-sdk/s3-presigned-post');
+var stream = require('stream');
+
+// src/adapters/s3-storage.adapter.ts
+var DEFAULT_EXPIRES_IN = 3600;
+var DEFAULT_MAX_SIZE_BYTES = 100 * 1024 * 1024;
+var DEFAULT_MIN_SIZE_BYTES = 1;
+var S3StorageAdapter = class {
+  client;
+  bucketResolver;
+  constructor(config) {
+    this.bucketResolver = typeof config.bucket === "function" ? config.bucket : () => config.bucket;
+    this.client = new clientS3.S3Client({
+      region: config.region,
+      credentials: {
+        accessKeyId: config.accessKeyId,
+        secretAccessKey: config.secretAccessKey
+      },
+      ...config.endpoint && {
+        endpoint: config.endpoint,
+        forcePathStyle: config.forcePathStyle ?? true
+      }
+    });
+  }
+  isNotFoundError(err) {
+    if (!(err instanceof Error)) return false;
+    const e = err;
+    return e.name === "NoSuchKey" || e.name === "NotFound" || e.$metadata?.httpStatusCode === 404;
+  }
+  getBucket(key) {
+    return this.bucketResolver(key);
+  }
+  async get(key) {
+    try {
+      const response = await this.client.send(
+        new clientS3.GetObjectCommand({ Bucket: this.getBucket(key), Key: key })
+      );
+      const body = response.Body;
+      if (body == null) return null;
+      const chunks = [];
+      for await (const chunk of body) {
+        chunks.push(chunk);
+      }
+      return Buffer.concat(chunks);
+    } catch (err) {
+      if (this.isNotFoundError(err)) return null;
+      throw err;
+    }
+  }
+  async put(key, value) {
+    await this.client.send(
+      new clientS3.PutObjectCommand({
+        Bucket: this.getBucket(key),
+        Key: key,
+        Body: value
+      })
+    );
+  }
+  async delete(key) {
+    try {
+      await this.client.send(new clientS3.DeleteObjectCommand({ Bucket: this.getBucket(key), Key: key }));
+    } catch (err) {
+      if (this.isNotFoundError(err)) return;
+      throw err;
+    }
+  }
+  async exists(key) {
+    try {
+      await this.client.send(new clientS3.HeadObjectCommand({ Bucket: this.getBucket(key), Key: key }));
+      return true;
+    } catch (err) {
+      if (this.isNotFoundError(err)) return false;
+      throw err;
+    }
+  }
+  async getSize(key) {
+    try {
+      const response = await this.client.send(
+        new clientS3.HeadObjectCommand({ Bucket: this.getBucket(key), Key: key })
+      );
+      const size = response.ContentLength;
+      return size != null ? size : null;
+    } catch (err) {
+      if (this.isNotFoundError(err)) return null;
+      throw err;
+    }
+  }
+  async getStream(key) {
+    try {
+      const response = await this.client.send(
+        new clientS3.GetObjectCommand({ Bucket: this.getBucket(key), Key: key })
+      );
+      const body = response.Body;
+      if (body == null) return null;
+      if (body instanceof stream.Readable) {
+        return stream.Readable.toWeb(body);
+      }
+      if (body instanceof ReadableStream) {
+        return body;
+      }
+      if (typeof body.stream === "function") {
+        return body.stream();
+      }
+      return null;
+    } catch (err) {
+      if (this.isNotFoundError(err)) return null;
+      throw err;
+    }
+  }
+  async getUrl(key, options) {
+    const expiresIn = options?.expiresIn ?? DEFAULT_EXPIRES_IN;
+    const command = new clientS3.GetObjectCommand({
+      Bucket: this.getBucket(key),
+      Key: key
+    });
+    return s3RequestPresigner.getSignedUrl(this.client, command, { expiresIn });
+  }
+  /**
+   * Create a presigned upload for direct-to-storage upload.
+   *
+   * - **POST**: Uses an S3 Policy to strictly enforce `Content-Type` and
+   *   `content-length-range` server-side. S3 rejects any upload violating these.
+   *   Best for web/browser clients using multipart forms.
+   *
+   * - **PUT**: Signs `ContentType`, `ContentLength`, and metadata headers into the URL.
+   *   S3 rejects any request that presents mismatched header values.
+   *   Best for mobile/API clients doing direct binary body uploads.
+   */
+  async createPresignedUpload(key, options) {
+    const {
+      method = "PUT",
+      contentType,
+      expiresIn = DEFAULT_EXPIRES_IN,
+      maxSizeBytes = DEFAULT_MAX_SIZE_BYTES,
+      minSizeBytes = DEFAULT_MIN_SIZE_BYTES,
+      metadata = {}
+    } = options;
+    const bucket = this.getBucket(key);
+    const metaHeaders = Object.fromEntries(
+      Object.entries(metadata).map(([k, v]) => [`x-amz-meta-${k}`, String(v)])
+    );
+    if (method === "POST") {
+      return this._createPresignedPost({
+        key,
+        bucket,
+        contentType,
+        expiresIn,
+        maxSizeBytes,
+        minSizeBytes,
+        metadata,
+        metaHeaders
+      });
+    }
+    return this._createPresignedPut({
+      key,
+      bucket,
+      contentType,
+      expiresIn,
+      maxSizeBytes,
+      metadata,
+      metaHeaders
+    });
+  }
+  async _createPresignedPost(params) {
+    const {
+      key,
+      bucket,
+      contentType,
+      expiresIn,
+      maxSizeBytes,
+      minSizeBytes,
+      metadata,
+      metaHeaders
+    } = params;
+    const conditions = [
+      // Enforce exact Content-Type — S3 rejects mismatches
+      { "Content-Type": contentType },
+      // Enforce file size range — S3 rejects files outside [min, max]
+      ["content-length-range", minSizeBytes, maxSizeBytes],
+      // Enforce each metadata k/v — S3 rejects if any value differs
+      ...Object.entries(metadata).map(([k, v]) => ({
+        [`x-amz-meta-${k}`]: v
+      }))
+    ];
+    const { url, fields } = await s3PresignedPost.createPresignedPost(this.client, {
+      Bucket: bucket,
+      Key: key,
+      Expires: expiresIn,
+      Conditions: conditions,
+      Fields: {
+        "Content-Type": contentType,
+        ...metaHeaders
+      }
+    });
+    return { method: "POST", url, fields };
+  }
+  async _createPresignedPut(params) {
+    const { key, bucket, contentType, expiresIn, maxSizeBytes, metadata, metaHeaders } = params;
+    const command = new clientS3.PutObjectCommand({
+      Bucket: bucket,
+      Key: key,
+      ContentType: contentType,
+      // Encoding ContentLength ties the signature to an exact body size.
+      // The client MUST send a Content-Length header that matches this value.
+      ContentLength: maxSizeBytes,
+      // User metadata is signed in — mismatches cause 403.
+      Metadata: Object.keys(metadata).length > 0 ? metadata : void 0
+    });
+    const url = await s3RequestPresigner.getSignedUrl(this.client, command, { expiresIn });
+    const headers = {
+      "Content-Type": contentType,
+      "Content-Length": String(maxSizeBytes),
+      ...metaHeaders
+    };
+    return { method: "PUT", url, headers };
+  }
+};
+
+exports.S3StorageAdapter = S3StorageAdapter;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters/s3-storage.adapter.ts"],"names":["S3Client","GetObjectCommand","PutObjectCommand","DeleteObjectCommand","HeadObjectCommand","Readable","getSignedUrl","createPresignedPost"],"mappings":"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","file":"index.js","sourcesContent":["import {\n  S3Client,\n  GetObjectCommand,\n  PutObjectCommand,\n  DeleteObjectCommand,\n  HeadObjectCommand,\n} from \"@aws-sdk/client-s3\";\nimport { getSignedUrl } from \"@aws-sdk/s3-request-presigner\";\nimport { createPresignedPost } from \"@aws-sdk/s3-presigned-post\";\nimport type { PresignedPostOptions } from \"@aws-sdk/s3-presigned-post\";\nimport { Readable } from \"node:stream\";\nimport type {\n  StorageAdapter,\n  GetUrlOptions,\n  PresignedUploadOptions,\n  PresignedUploadResult,\n} from \"@better-media/core\";\nimport type { S3StorageConfig } from \"../interfaces/s3-storage-config.interface\";\n\nconst DEFAULT_EXPIRES_IN = 3600; // 1 hour\nconst DEFAULT_MAX_SIZE_BYTES = 100 * 1024 * 1024; // 100 MB\nconst DEFAULT_MIN_SIZE_BYTES = 1; // at least 1 byte\n\n/**\n * S3 storage adapter for production deployments.\n * Supports AWS S3 and S3-compatible object storage (MinIO, etc.).\n */\nexport class S3StorageAdapter implements StorageAdapter {\n  private readonly client: S3Client;\n  private readonly bucketResolver: (key: string) => string;\n\n  constructor(config: S3StorageConfig) {\n    this.bucketResolver =\n      typeof config.bucket === \"function\" ? config.bucket : () => config.bucket as string;\n    this.client = new S3Client({\n      region: config.region,\n      credentials: {\n        accessKeyId: config.accessKeyId,\n        secretAccessKey: config.secretAccessKey,\n      },\n      ...(config.endpoint && {\n        endpoint: config.endpoint,\n        forcePathStyle: config.forcePathStyle ?? true,\n      }),\n    });\n  }\n\n  private isNotFoundError(err: unknown): boolean {\n    if (!(err instanceof Error)) return false;\n    const e = err as { name?: string; $metadata?: { httpStatusCode?: number } };\n    return e.name === \"NoSuchKey\" || e.name === \"NotFound\" || e.$metadata?.httpStatusCode === 404;\n  }\n\n  private getBucket(key: string): string {\n    return this.bucketResolver(key);\n  }\n\n  async get(key: string): Promise<Buffer | null> {\n    try {\n      const response = await this.client.send(\n        new GetObjectCommand({ Bucket: this.getBucket(key), Key: key })\n      );\n      const body = response.Body;\n      if (body == null) return null;\n      const chunks: Uint8Array[] = [];\n      for await (const chunk of body as AsyncIterable<Uint8Array>) {\n        chunks.push(chunk);\n      }\n      return Buffer.concat(chunks);\n    } catch (err) {\n      if (this.isNotFoundError(err)) return null;\n      throw err;\n    }\n  }\n\n  async put(key: string, value: Buffer): Promise<void> {\n    await this.client.send(\n      new PutObjectCommand({\n        Bucket: this.getBucket(key),\n        Key: key,\n        Body: value,\n      })\n    );\n  }\n\n  async delete(key: string): Promise<void> {\n    try {\n      await this.client.send(new DeleteObjectCommand({ Bucket: this.getBucket(key), Key: key }));\n    } catch (err) {\n      if (this.isNotFoundError(err)) return;\n      throw err;\n    }\n  }\n\n  async exists(key: string): Promise<boolean> {\n    try {\n      await this.client.send(new HeadObjectCommand({ Bucket: this.getBucket(key), Key: key }));\n      return true;\n    } catch (err) {\n      if (this.isNotFoundError(err)) return false;\n      throw err;\n    }\n  }\n\n  async getSize(key: string): Promise<number | null> {\n    try {\n      const response = await this.client.send(\n        new HeadObjectCommand({ Bucket: this.getBucket(key), Key: key })\n      );\n      const size = response.ContentLength;\n      return size != null ? size : null;\n    } catch (err) {\n      if (this.isNotFoundError(err)) return null;\n      throw err;\n    }\n  }\n\n  async getStream(key: string): Promise<ReadableStream<Uint8Array> | null> {\n    try {\n      const response = await this.client.send(\n        new GetObjectCommand({ Bucket: this.getBucket(key), Key: key })\n      );\n      const body = response.Body;\n      if (body == null) return null;\n      if (body instanceof Readable) {\n        return Readable.toWeb(body) as ReadableStream<Uint8Array>;\n      }\n      if (body instanceof ReadableStream) {\n        return body as ReadableStream<Uint8Array>;\n      }\n      if (typeof (body as Blob).stream === \"function\") {\n        return (body as Blob).stream() as ReadableStream<Uint8Array>;\n      }\n      return null;\n    } catch (err) {\n      if (this.isNotFoundError(err)) return null;\n      throw err;\n    }\n  }\n\n  async getUrl(key: string, options?: GetUrlOptions): Promise<string> {\n    const expiresIn = options?.expiresIn ?? DEFAULT_EXPIRES_IN;\n    const command = new GetObjectCommand({\n      Bucket: this.getBucket(key),\n      Key: key,\n    });\n    return getSignedUrl(this.client, command, { expiresIn });\n  }\n\n  /**\n   * Create a presigned upload for direct-to-storage upload.\n   *\n   * - **POST**: Uses an S3 Policy to strictly enforce `Content-Type` and\n   *   `content-length-range` server-side. S3 rejects any upload violating these.\n   *   Best for web/browser clients using multipart forms.\n   *\n   * - **PUT**: Signs `ContentType`, `ContentLength`, and metadata headers into the URL.\n   *   S3 rejects any request that presents mismatched header values.\n   *   Best for mobile/API clients doing direct binary body uploads.\n   */\n  async createPresignedUpload(\n    key: string,\n    options: PresignedUploadOptions\n  ): Promise<PresignedUploadResult> {\n    const {\n      method = \"PUT\",\n      contentType,\n      expiresIn = DEFAULT_EXPIRES_IN,\n      maxSizeBytes = DEFAULT_MAX_SIZE_BYTES,\n      minSizeBytes = DEFAULT_MIN_SIZE_BYTES,\n      metadata = {},\n    } = options;\n\n    const bucket = this.getBucket(key);\n    // Build x-amz-meta-* header map for user metadata\n    const metaHeaders: Record<string, string> = Object.fromEntries(\n      Object.entries(metadata).map(([k, v]): [string, string] => [`x-amz-meta-${k}`, String(v)])\n    );\n\n    if (method === \"POST\") {\n      return this._createPresignedPost({\n        key,\n        bucket,\n        contentType,\n        expiresIn,\n        maxSizeBytes,\n        minSizeBytes,\n        metadata,\n        metaHeaders,\n      });\n    }\n\n    return this._createPresignedPut({\n      key,\n      bucket,\n      contentType,\n      expiresIn,\n      maxSizeBytes,\n      metadata,\n      metaHeaders,\n    });\n  }\n\n  private async _createPresignedPost(params: {\n    key: string;\n    bucket: string;\n    contentType: string;\n    expiresIn: number;\n    maxSizeBytes: number;\n    minSizeBytes: number;\n    metadata: Record<string, string>;\n    metaHeaders: Record<string, string>;\n  }): Promise<PresignedUploadResult> {\n    const {\n      key,\n      bucket,\n      contentType,\n      expiresIn,\n      maxSizeBytes,\n      minSizeBytes,\n      metadata,\n      metaHeaders,\n    } = params;\n\n    // Build the conditions array using the SDK's element type\n    const conditions: NonNullable<PresignedPostOptions[\"Conditions\"]> = [\n      // Enforce exact Content-Type — S3 rejects mismatches\n      { \"Content-Type\": contentType },\n      // Enforce file size range — S3 rejects files outside [min, max]\n      [\"content-length-range\", minSizeBytes, maxSizeBytes],\n      // Enforce each metadata k/v — S3 rejects if any value differs\n      ...Object.entries(metadata).map(([k, v]) => ({\n        [`x-amz-meta-${k}`]: v,\n      })),\n    ];\n\n    const { url, fields } = await createPresignedPost(this.client, {\n      Bucket: bucket,\n      Key: key,\n      Expires: expiresIn,\n      Conditions: conditions,\n      Fields: {\n        \"Content-Type\": contentType,\n        ...metaHeaders,\n      },\n    });\n\n    return { method: \"POST\", url, fields };\n  }\n\n  private async _createPresignedPut(params: {\n    key: string;\n    bucket: string;\n    contentType: string;\n    expiresIn: number;\n    maxSizeBytes: number;\n    metadata: Record<string, string>;\n    metaHeaders: Record<string, string>;\n  }): Promise<PresignedUploadResult> {\n    const { key, bucket, contentType, expiresIn, maxSizeBytes, metadata, metaHeaders } = params;\n\n    // All fields set on PutObjectCommand are hashed into the signature.\n    // S3 will return 403 for any request that presents different header values.\n    const command = new PutObjectCommand({\n      Bucket: bucket,\n      Key: key,\n      ContentType: contentType,\n      // Encoding ContentLength ties the signature to an exact body size.\n      // The client MUST send a Content-Length header that matches this value.\n      ContentLength: maxSizeBytes,\n      // User metadata is signed in — mismatches cause 403.\n      Metadata: Object.keys(metadata).length > 0 ? metadata : undefined,\n    });\n\n    const url = await getSignedUrl(this.client, command, { expiresIn });\n\n    // Surface the required headers so callers know exactly what to send.\n    const headers: Record<string, string> = {\n      \"Content-Type\": contentType,\n      \"Content-Length\": String(maxSizeBytes),\n      ...metaHeaders,\n    };\n\n    return { method: \"PUT\", url, headers };\n  }\n}\n"]}

package/dist/index.mjs

@@ -0,0 +1,223 @@
+import { S3Client, GetObjectCommand, PutObjectCommand, DeleteObjectCommand, HeadObjectCommand } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+import { createPresignedPost } from '@aws-sdk/s3-presigned-post';
+import { Readable } from 'stream';
+
+// src/adapters/s3-storage.adapter.ts
+var DEFAULT_EXPIRES_IN = 3600;
+var DEFAULT_MAX_SIZE_BYTES = 100 * 1024 * 1024;
+var DEFAULT_MIN_SIZE_BYTES = 1;
+var S3StorageAdapter = class {
+  client;
+  bucketResolver;
+  constructor(config) {
+    this.bucketResolver = typeof config.bucket === "function" ? config.bucket : () => config.bucket;
+    this.client = new S3Client({
+      region: config.region,
+      credentials: {
+        accessKeyId: config.accessKeyId,
+        secretAccessKey: config.secretAccessKey
+      },
+      ...config.endpoint && {
+        endpoint: config.endpoint,
+        forcePathStyle: config.forcePathStyle ?? true
+      }
+    });
+  }
+  isNotFoundError(err) {
+    if (!(err instanceof Error)) return false;
+    const e = err;
+    return e.name === "NoSuchKey" || e.name === "NotFound" || e.$metadata?.httpStatusCode === 404;
+  }
+  getBucket(key) {
+    return this.bucketResolver(key);
+  }
+  async get(key) {
+    try {
+      const response = await this.client.send(
+        new GetObjectCommand({ Bucket: this.getBucket(key), Key: key })
+      );
+      const body = response.Body;
+      if (body == null) return null;
+      const chunks = [];
+      for await (const chunk of body) {
+        chunks.push(chunk);
+      }
+      return Buffer.concat(chunks);
+    } catch (err) {
+      if (this.isNotFoundError(err)) return null;
+      throw err;
+    }
+  }
+  async put(key, value) {
+    await this.client.send(
+      new PutObjectCommand({
+        Bucket: this.getBucket(key),
+        Key: key,
+        Body: value
+      })
+    );
+  }
+  async delete(key) {
+    try {
+      await this.client.send(new DeleteObjectCommand({ Bucket: this.getBucket(key), Key: key }));
+    } catch (err) {
+      if (this.isNotFoundError(err)) return;
+      throw err;
+    }
+  }
+  async exists(key) {
+    try {
+      await this.client.send(new HeadObjectCommand({ Bucket: this.getBucket(key), Key: key }));
+      return true;
+    } catch (err) {
+      if (this.isNotFoundError(err)) return false;
+      throw err;
+    }
+  }
+  async getSize(key) {
+    try {
+      const response = await this.client.send(
+        new HeadObjectCommand({ Bucket: this.getBucket(key), Key: key })
+      );
+      const size = response.ContentLength;
+      return size != null ? size : null;
+    } catch (err) {
+      if (this.isNotFoundError(err)) return null;
+      throw err;
+    }
+  }
+  async getStream(key) {
+    try {
+      const response = await this.client.send(
+        new GetObjectCommand({ Bucket: this.getBucket(key), Key: key })
+      );
+      const body = response.Body;
+      if (body == null) return null;
+      if (body instanceof Readable) {
+        return Readable.toWeb(body);
+      }
+      if (body instanceof ReadableStream) {
+        return body;
+      }
+      if (typeof body.stream === "function") {
+        return body.stream();
+      }
+      return null;
+    } catch (err) {
+      if (this.isNotFoundError(err)) return null;
+      throw err;
+    }
+  }
+  async getUrl(key, options) {
+    const expiresIn = options?.expiresIn ?? DEFAULT_EXPIRES_IN;
+    const command = new GetObjectCommand({
+      Bucket: this.getBucket(key),
+      Key: key
+    });
+    return getSignedUrl(this.client, command, { expiresIn });
+  }
+  /**
+   * Create a presigned upload for direct-to-storage upload.
+   *
+   * - **POST**: Uses an S3 Policy to strictly enforce `Content-Type` and
+   *   `content-length-range` server-side. S3 rejects any upload violating these.
+   *   Best for web/browser clients using multipart forms.
+   *
+   * - **PUT**: Signs `ContentType`, `ContentLength`, and metadata headers into the URL.
+   *   S3 rejects any request that presents mismatched header values.
+   *   Best for mobile/API clients doing direct binary body uploads.
+   */
+  async createPresignedUpload(key, options) {
+    const {
+      method = "PUT",
+      contentType,
+      expiresIn = DEFAULT_EXPIRES_IN,
+      maxSizeBytes = DEFAULT_MAX_SIZE_BYTES,
+      minSizeBytes = DEFAULT_MIN_SIZE_BYTES,
+      metadata = {}
+    } = options;
+    const bucket = this.getBucket(key);
+    const metaHeaders = Object.fromEntries(
+      Object.entries(metadata).map(([k, v]) => [`x-amz-meta-${k}`, String(v)])
+    );
+    if (method === "POST") {
+      return this._createPresignedPost({
+        key,
+        bucket,
+        contentType,
+        expiresIn,
+        maxSizeBytes,
+        minSizeBytes,
+        metadata,
+        metaHeaders
+      });
+    }
+    return this._createPresignedPut({
+      key,
+      bucket,
+      contentType,
+      expiresIn,
+      maxSizeBytes,
+      metadata,
+      metaHeaders
+    });
+  }
+  async _createPresignedPost(params) {
+    const {
+      key,
+      bucket,
+      contentType,
+      expiresIn,
+      maxSizeBytes,
+      minSizeBytes,
+      metadata,
+      metaHeaders
+    } = params;
+    const conditions = [
+      // Enforce exact Content-Type — S3 rejects mismatches
+      { "Content-Type": contentType },
+      // Enforce file size range — S3 rejects files outside [min, max]
+      ["content-length-range", minSizeBytes, maxSizeBytes],
+      // Enforce each metadata k/v — S3 rejects if any value differs
+      ...Object.entries(metadata).map(([k, v]) => ({
+        [`x-amz-meta-${k}`]: v
+      }))
+    ];
+    const { url, fields } = await createPresignedPost(this.client, {
+      Bucket: bucket,
+      Key: key,
+      Expires: expiresIn,
+      Conditions: conditions,
+      Fields: {
+        "Content-Type": contentType,
+        ...metaHeaders
+      }
+    });
+    return { method: "POST", url, fields };
+  }
+  async _createPresignedPut(params) {
+    const { key, bucket, contentType, expiresIn, maxSizeBytes, metadata, metaHeaders } = params;
+    const command = new PutObjectCommand({
+      Bucket: bucket,
+      Key: key,
+      ContentType: contentType,
+      // Encoding ContentLength ties the signature to an exact body size.
+      // The client MUST send a Content-Length header that matches this value.
+      ContentLength: maxSizeBytes,
+      // User metadata is signed in — mismatches cause 403.
+      Metadata: Object.keys(metadata).length > 0 ? metadata : void 0
+    });
+    const url = await getSignedUrl(this.client, command, { expiresIn });
+    const headers = {
+      "Content-Type": contentType,
+      "Content-Length": String(maxSizeBytes),
+      ...metaHeaders
+    };
+    return { method: "PUT", url, headers };
+  }
+};
+
+export { S3StorageAdapter };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/adapters/s3-storage.adapter.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["import {\n  S3Client,\n  GetObjectCommand,\n  PutObjectCommand,\n  DeleteObjectCommand,\n  HeadObjectCommand,\n} from \"@aws-sdk/client-s3\";\nimport { getSignedUrl } from \"@aws-sdk/s3-request-presigner\";\nimport { createPresignedPost } from \"@aws-sdk/s3-presigned-post\";\nimport type { PresignedPostOptions } from \"@aws-sdk/s3-presigned-post\";\nimport { Readable } from \"node:stream\";\nimport type {\n  StorageAdapter,\n  GetUrlOptions,\n  PresignedUploadOptions,\n  PresignedUploadResult,\n} from \"@better-media/core\";\nimport type { S3StorageConfig } from \"../interfaces/s3-storage-config.interface\";\n\nconst DEFAULT_EXPIRES_IN = 3600; // 1 hour\nconst DEFAULT_MAX_SIZE_BYTES = 100 * 1024 * 1024; // 100 MB\nconst DEFAULT_MIN_SIZE_BYTES = 1; // at least 1 byte\n\n/**\n * S3 storage adapter for production deployments.\n * Supports AWS S3 and S3-compatible object storage (MinIO, etc.).\n */\nexport class S3StorageAdapter implements StorageAdapter {\n  private readonly client: S3Client;\n  private readonly bucketResolver: (key: string) => string;\n\n  constructor(config: S3StorageConfig) {\n    this.bucketResolver =\n      typeof config.bucket === \"function\" ? config.bucket : () => config.bucket as string;\n    this.client = new S3Client({\n      region: config.region,\n      credentials: {\n        accessKeyId: config.accessKeyId,\n        secretAccessKey: config.secretAccessKey,\n      },\n      ...(config.endpoint && {\n        endpoint: config.endpoint,\n        forcePathStyle: config.forcePathStyle ?? true,\n      }),\n    });\n  }\n\n  private isNotFoundError(err: unknown): boolean {\n    if (!(err instanceof Error)) return false;\n    const e = err as { name?: string; $metadata?: { httpStatusCode?: number } };\n    return e.name === \"NoSuchKey\" || e.name === \"NotFound\" || e.$metadata?.httpStatusCode === 404;\n  }\n\n  private getBucket(key: string): string {\n    return this.bucketResolver(key);\n  }\n\n  async get(key: string): Promise<Buffer | null> {\n    try {\n      const response = await this.client.send(\n        new GetObjectCommand({ Bucket: this.getBucket(key), Key: key })\n      );\n      const body = response.Body;\n      if (body == null) return null;\n      const chunks: Uint8Array[] = [];\n      for await (const chunk of body as AsyncIterable<Uint8Array>) {\n        chunks.push(chunk);\n      }\n      return Buffer.concat(chunks);\n    } catch (err) {\n      if (this.isNotFoundError(err)) return null;\n      throw err;\n    }\n  }\n\n  async put(key: string, value: Buffer): Promise<void> {\n    await this.client.send(\n      new PutObjectCommand({\n        Bucket: this.getBucket(key),\n        Key: key,\n        Body: value,\n      })\n    );\n  }\n\n  async delete(key: string): Promise<void> {\n    try {\n      await this.client.send(new DeleteObjectCommand({ Bucket: this.getBucket(key), Key: key }));\n    } catch (err) {\n      if (this.isNotFoundError(err)) return;\n      throw err;\n    }\n  }\n\n  async exists(key: string): Promise<boolean> {\n    try {\n      await this.client.send(new HeadObjectCommand({ Bucket: this.getBucket(key), Key: key }));\n      return true;\n    } catch (err) {\n      if (this.isNotFoundError(err)) return false;\n      throw err;\n    }\n  }\n\n  async getSize(key: string): Promise<number | null> {\n    try {\n      const response = await this.client.send(\n        new HeadObjectCommand({ Bucket: this.getBucket(key), Key: key })\n      );\n      const size = response.ContentLength;\n      return size != null ? size : null;\n    } catch (err) {\n      if (this.isNotFoundError(err)) return null;\n      throw err;\n    }\n  }\n\n  async getStream(key: string): Promise<ReadableStream<Uint8Array> | null> {\n    try {\n      const response = await this.client.send(\n        new GetObjectCommand({ Bucket: this.getBucket(key), Key: key })\n      );\n      const body = response.Body;\n      if (body == null) return null;\n      if (body instanceof Readable) {\n        return Readable.toWeb(body) as ReadableStream<Uint8Array>;\n      }\n      if (body instanceof ReadableStream) {\n        return body as ReadableStream<Uint8Array>;\n      }\n      if (typeof (body as Blob).stream === \"function\") {\n        return (body as Blob).stream() as ReadableStream<Uint8Array>;\n      }\n      return null;\n    } catch (err) {\n      if (this.isNotFoundError(err)) return null;\n      throw err;\n    }\n  }\n\n  async getUrl(key: string, options?: GetUrlOptions): Promise<string> {\n    const expiresIn = options?.expiresIn ?? DEFAULT_EXPIRES_IN;\n    const command = new GetObjectCommand({\n      Bucket: this.getBucket(key),\n      Key: key,\n    });\n    return getSignedUrl(this.client, command, { expiresIn });\n  }\n\n  /**\n   * Create a presigned upload for direct-to-storage upload.\n   *\n   * - **POST**: Uses an S3 Policy to strictly enforce `Content-Type` and\n   *   `content-length-range` server-side. S3 rejects any upload violating these.\n   *   Best for web/browser clients using multipart forms.\n   *\n   * - **PUT**: Signs `ContentType`, `ContentLength`, and metadata headers into the URL.\n   *   S3 rejects any request that presents mismatched header values.\n   *   Best for mobile/API clients doing direct binary body uploads.\n   */\n  async createPresignedUpload(\n    key: string,\n    options: PresignedUploadOptions\n  ): Promise<PresignedUploadResult> {\n    const {\n      method = \"PUT\",\n      contentType,\n      expiresIn = DEFAULT_EXPIRES_IN,\n      maxSizeBytes = DEFAULT_MAX_SIZE_BYTES,\n      minSizeBytes = DEFAULT_MIN_SIZE_BYTES,\n      metadata = {},\n    } = options;\n\n    const bucket = this.getBucket(key);\n    // Build x-amz-meta-* header map for user metadata\n    const metaHeaders: Record<string, string> = Object.fromEntries(\n      Object.entries(metadata).map(([k, v]): [string, string] => [`x-amz-meta-${k}`, String(v)])\n    );\n\n    if (method === \"POST\") {\n      return this._createPresignedPost({\n        key,\n        bucket,\n        contentType,\n        expiresIn,\n        maxSizeBytes,\n        minSizeBytes,\n        metadata,\n        metaHeaders,\n      });\n    }\n\n    return this._createPresignedPut({\n      key,\n      bucket,\n      contentType,\n      expiresIn,\n      maxSizeBytes,\n      metadata,\n      metaHeaders,\n    });\n  }\n\n  private async _createPresignedPost(params: {\n    key: string;\n    bucket: string;\n    contentType: string;\n    expiresIn: number;\n    maxSizeBytes: number;\n    minSizeBytes: number;\n    metadata: Record<string, string>;\n    metaHeaders: Record<string, string>;\n  }): Promise<PresignedUploadResult> {\n    const {\n      key,\n      bucket,\n      contentType,\n      expiresIn,\n      maxSizeBytes,\n      minSizeBytes,\n      metadata,\n      metaHeaders,\n    } = params;\n\n    // Build the conditions array using the SDK's element type\n    const conditions: NonNullable<PresignedPostOptions[\"Conditions\"]> = [\n      // Enforce exact Content-Type — S3 rejects mismatches\n      { \"Content-Type\": contentType },\n      // Enforce file size range — S3 rejects files outside [min, max]\n      [\"content-length-range\", minSizeBytes, maxSizeBytes],\n      // Enforce each metadata k/v — S3 rejects if any value differs\n      ...Object.entries(metadata).map(([k, v]) => ({\n        [`x-amz-meta-${k}`]: v,\n      })),\n    ];\n\n    const { url, fields } = await createPresignedPost(this.client, {\n      Bucket: bucket,\n      Key: key,\n      Expires: expiresIn,\n      Conditions: conditions,\n      Fields: {\n        \"Content-Type\": contentType,\n        ...metaHeaders,\n      },\n    });\n\n    return { method: \"POST\", url, fields };\n  }\n\n  private async _createPresignedPut(params: {\n    key: string;\n    bucket: string;\n    contentType: string;\n    expiresIn: number;\n    maxSizeBytes: number;\n    metadata: Record<string, string>;\n    metaHeaders: Record<string, string>;\n  }): Promise<PresignedUploadResult> {\n    const { key, bucket, contentType, expiresIn, maxSizeBytes, metadata, metaHeaders } = params;\n\n    // All fields set on PutObjectCommand are hashed into the signature.\n    // S3 will return 403 for any request that presents different header values.\n    const command = new PutObjectCommand({\n      Bucket: bucket,\n      Key: key,\n      ContentType: contentType,\n      // Encoding ContentLength ties the signature to an exact body size.\n      // The client MUST send a Content-Length header that matches this value.\n      ContentLength: maxSizeBytes,\n      // User metadata is signed in — mismatches cause 403.\n      Metadata: Object.keys(metadata).length > 0 ? metadata : undefined,\n    });\n\n    const url = await getSignedUrl(this.client, command, { expiresIn });\n\n    // Surface the required headers so callers know exactly what to send.\n    const headers: Record<string, string> = {\n      \"Content-Type\": contentType,\n      \"Content-Length\": String(maxSizeBytes),\n      ...metaHeaders,\n    };\n\n    return { method: \"PUT\", url, headers };\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@better-media/adapter-storage-s3",
+  "version": "0.1.0",
+  "description": "S3 storage adapter for Better Media",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.700.0",
+    "@aws-sdk/s3-presigned-post": "^3.700.0",
+    "@aws-sdk/s3-request-presigner": "^3.700.0",
+    "@better-media/core": "0.1.0"
+  },
+  "keywords": [
+    "better-media",
+    "storage",
+    "s3",
+    "aws",
+    "minio",
+    "adapter"
+  ],
+  "author": "Abenezer Atnafu",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AbenezerAtnafu/better-media.git"
+  },
+  "homepage": "https://better-media.dev",
+  "bugs": {
+    "url": "https://github.com/AbenezerAtnafu/better-media/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "jest"
+  }
+}