@nextlyhq/storage-s3 0.0.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 NextlyHQ <info@nextlyhq.com>
+
+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,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# @nextlyhq/storage-s3
+
+Amazon S3 (and S3-compatible: Cloudflare R2, MinIO, Backblaze B2, Wasabi, DigitalOcean Spaces) storage adapter for Nextly.
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@nextlyhq/storage-s3"><img alt="npm" src="https://img.shields.io/npm/v/@nextlyhq/storage-s3?style=flat-square&label=npm&color=cb3837" /></a>
+  <a href="https://github.com/nextlyhq/nextly/blob/main/LICENSE.md"><img alt="License" src="https://img.shields.io/github/license/nextlyhq/nextly?style=flat-square&color=blue" /></a>
+  <a href="https://nextlyhq.com/docs"><img alt="Status" src="https://img.shields.io/badge/status-alpha-orange?style=flat-square" /></a>
+</p>
+
+> [!IMPORTANT]
+> Nextly is in alpha. APIs may change before 1.0. Pin exact versions in production.
+
+## What it is
+
+Stores Nextly media uploads on Amazon S3 or any S3-compatible object store. R2, MinIO, B2, Wasabi, and DigitalOcean Spaces all work via the same adapter; you do not need separate packages.
+
+> **You do not need this for development.** Nextly's default storage is local disk under `./public/uploads/`. Install this when you are ready to move uploads to a cloud object store, typically for production deployments.
+
+## Installation
+
+```bash
+pnpm add @nextlyhq/storage-s3
+```
+
+## Quick usage
+
+Register the storage adapter in `nextly.config.ts`:
+
+```ts
+import { defineConfig } from "nextly/config";
+import { s3Storage } from "@nextlyhq/storage-s3";
+
+export default defineConfig({
+  storage: [
+    s3Storage({
+      bucket: process.env.S3_BUCKET!,
+      region: process.env.AWS_REGION!,
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+      collections: { media: true },
+    }),
+  ],
+});
+```
+
+## Required environment variables
+
+| Variable                | Required?                   | Default | Notes                         |
+| ----------------------- | --------------------------- | ------- | ----------------------------- |
+| `S3_BUCKET`             | yes                         | (none)  |                               |
+| `AWS_REGION`            | yes for AWS                 | (none)  | Use `auto` for Cloudflare R2. |
+| `AWS_ACCESS_KEY_ID`     | yes (if not using IAM role) | (none)  |                               |
+| `AWS_SECRET_ACCESS_KEY` | yes (if not using IAM role) | (none)  |                               |
+
+You can also pass these explicitly to `s3Storage(...)` instead of using env vars.
+
+## Cloudflare R2
+
+```ts
+s3Storage({
+  bucket: process.env.R2_BUCKET!,
+  region: "auto",
+  accessKeyId: process.env.R2_ACCESS_KEY_ID!,
+  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
+  endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
+  publicUrl: process.env.R2_PUBLIC_URL,
+  collections: { media: true },
+});
+```
+
+## MinIO
+
+```ts
+s3Storage({
+  bucket: "my-bucket",
+  region: "us-east-1",
+  endpoint: "https://minio.example.com",
+  forcePathStyle: true,
+  accessKeyId: process.env.MINIO_ACCESS_KEY!,
+  secretAccessKey: process.env.MINIO_SECRET_KEY!,
+  collections: { media: true },
+});
+```
+
+## Per-collection configuration
+
+```ts
+s3Storage({
+  bucket: "my-bucket",
+  region: "us-east-1",
+  collections: {
+    media: true,
+    "private-docs": {
+      prefix: "private/",
+      clientUploads: true,
+      signedDownloads: true,
+      signedUrlExpiresIn: 3600,
+    },
+  },
+});
+```
+
+## Main exports
+
+- `s3Storage`: plugin factory for `defineConfig.storage`
+- `S3StorageAdapter`: the adapter class (advanced)
+- Type exports: `S3StorageConfig`, `S3CollectionConfig`
+
+## Compatibility
+
+| Tool     | Version                                                                 |
+| -------- | ----------------------------------------------------------------------- |
+| Node.js  | 20+                                                                     |
+| `nextly` | 0.0.x                                                                   |
+| Stores   | AWS S3, Cloudflare R2, MinIO, Backblaze B2, Wasabi, DigitalOcean Spaces |
+
+## Documentation
+
+- [**Media and storage docs**](https://nextlyhq.com/docs/guides/media-storage)
+
+## Related packages
+
+- [`@nextlyhq/storage-vercel-blob`](../storage-vercel-blob)
+- [`@nextlyhq/storage-uploadthing`](../storage-uploadthing)
+
+## License
+
+[MIT](../../LICENSE.md)

package/dist/index.cjs

@@ -0,0 +1,475 @@
+'use strict';
+
+var clientS3 = require('@aws-sdk/client-s3');
+var libStorage = require('@aws-sdk/lib-storage');
+var s3RequestPresigner = require('@aws-sdk/s3-request-presigner');
+
+// src/adapter.ts
+var S3StorageAdapter = class {
+  /**
+   * Create a new S3 storage adapter.
+   *
+   * @param config - S3 storage configuration
+   * @throws Error if bucket or region is not provided
+   */
+  constructor(config) {
+    this.config = config;
+    if (!config.bucket) {
+      throw new Error("@nextly/storage-s3: bucket is required");
+    }
+    if (!config.region) {
+      throw new Error("@nextly/storage-s3: region is required");
+    }
+    this.isR2 = config.endpoint?.includes("r2.cloudflarestorage.com") ?? false;
+    this.resolvedConfig = {
+      bucket: config.bucket,
+      region: config.region,
+      endpoint: config.endpoint,
+      forcePathStyle: config.forcePathStyle ?? false,
+      acl: config.acl ?? "private",
+      publicUrl: config.publicUrl,
+      cacheControl: config.cacheControl ?? "public, max-age=31536000",
+      contentDisposition: config.contentDisposition,
+      signedUrlExpiresIn: config.signedUrlExpiresIn ?? 3600
+    };
+    const credentials = this.buildCredentials();
+    this.client = new clientS3.S3Client({
+      region: config.region,
+      endpoint: config.endpoint,
+      credentials,
+      forcePathStyle: this.resolvedConfig.forcePathStyle,
+      ...config.config
+    });
+  }
+  client;
+  resolvedConfig;
+  isR2;
+  /**
+   * Build AWS credentials from config.
+   * Supports explicit credentials or falls back to SDK default chain.
+   */
+  buildCredentials() {
+    if (this.config.accessKeyId && this.config.secretAccessKey) {
+      return {
+        accessKeyId: this.config.accessKeyId,
+        secretAccessKey: this.config.secretAccessKey
+      };
+    }
+    if (this.config.config?.credentials) {
+      return void 0;
+    }
+    return void 0;
+  }
+  // ============================================================
+  // Core IStorageAdapter Methods
+  // ============================================================
+  /**
+   * Upload file to S3.
+   *
+   * Uses AWS SDK v3's Upload class from @aws-sdk/lib-storage which:
+   * - Automatically handles multipart upload for large files (>5MB)
+   * - Provides progress tracking capability
+   * - Includes retry logic
+   * - Optimizes upload performance
+   *
+   * @param buffer - File content as Buffer
+   * @param options - Upload options (filename, mimeType, folder, collection)
+   * @returns Upload result with URL and storage path
+   */
+  async upload(buffer, options) {
+    const key = this.generateKey(options.filename, options.folder);
+    const uploadParams = {
+      Bucket: this.resolvedConfig.bucket,
+      Key: key,
+      Body: buffer,
+      ContentType: options.contentType || options.mimeType,
+      CacheControl: this.resolvedConfig.cacheControl
+    };
+    if (!this.isR2) {
+      uploadParams.ACL = this.resolvedConfig.acl;
+    }
+    const disposition = options.contentDisposition ?? this.resolvedConfig.contentDisposition;
+    if (disposition) {
+      const filename = this.sanitizeFilename(options.filename);
+      uploadParams.ContentDisposition = disposition === "attachment" ? `attachment; filename="${filename}"` : "inline";
+    }
+    uploadParams.Metadata = {
+      "original-filename": options.filename
+    };
+    const upload = new libStorage.Upload({
+      client: this.client,
+      params: uploadParams
+    });
+    await upload.done();
+    return {
+      url: this.getPublicUrl(key),
+      path: key
+    };
+  }
+  /**
+   * Delete file from S3.
+   *
+   * @param filePath - Storage path/key to delete
+   */
+  async delete(filePath) {
+    const command = new clientS3.DeleteObjectCommand({
+      Bucket: this.resolvedConfig.bucket,
+      Key: filePath
+    });
+    await this.client.send(command);
+  }
+  /**
+   * Bulk delete files from S3 using a single API call per 1000 keys.
+   *
+   * Uses AWS SDK v3's DeleteObjectsCommand which supports up to 1000 keys per
+   * request. Automatically batches larger arrays and collects per-key results.
+   *
+   * @param filePaths - Storage paths/keys to delete
+   * @returns Object with arrays of successful and failed deletions
+   */
+  async bulkDelete(filePaths) {
+    const successful = [];
+    const failed = [];
+    const maxBatchSize = 1e3;
+    for (let i = 0; i < filePaths.length; i += maxBatchSize) {
+      const batch = filePaths.slice(i, i + maxBatchSize);
+      const command = new clientS3.DeleteObjectsCommand({
+        Bucket: this.resolvedConfig.bucket,
+        Delete: {
+          Objects: batch.map((key) => ({ Key: key })),
+          Quiet: false
+        }
+      });
+      const response = await this.client.send(command);
+      if (response.Errors && response.Errors.length > 0) {
+        for (const err of response.Errors) {
+          if (err.Key) {
+            failed.push({
+              filePath: err.Key,
+              error: err.Message ?? "Unknown S3 delete error"
+            });
+          }
+        }
+      }
+      if (response.Deleted) {
+        for (const del of response.Deleted) {
+          if (del.Key) {
+            successful.push(del.Key);
+          }
+        }
+      }
+    }
+    return { successful, failed };
+  }
+  /**
+   * Check if file exists in S3.
+   *
+   * Uses HeadObject command which is more efficient than GetObject
+   * for existence checks (doesn't download the file).
+   *
+   * @param filePath - Storage path/key to check
+   * @returns true if file exists, false otherwise
+   */
+  async exists(filePath) {
+    try {
+      const command = new clientS3.HeadObjectCommand({
+        Bucket: this.resolvedConfig.bucket,
+        Key: filePath
+      });
+      await this.client.send(command);
+      return true;
+    } catch (error) {
+      if (this.isNotFoundError(error)) {
+        return false;
+      }
+      throw error;
+    }
+  }
+  /**
+   * Get public URL for S3 file.
+   *
+   * Priority order:
+   * 1. Custom publicUrl (CDN or custom domain) if configured
+   * 2. Standard S3 URL based on region and bucket
+   *
+   * For R2: Requires publicUrl configuration (R2 has no default public URLs).
+   *
+   * @param filePath - Storage path/key
+   * @returns Public URL to access the file
+   * @throws Error if R2 is used without publicUrl configuration
+   */
+  getPublicUrl(filePath) {
+    if (this.resolvedConfig.publicUrl) {
+      const baseUrl = this.resolvedConfig.publicUrl.replace(/\/$/, "");
+      return `${baseUrl}/${filePath}`;
+    }
+    if (this.isR2) {
+      throw new Error(
+        "@nextly/storage-s3: Cloudflare R2 requires publicUrl configuration.\n\nR2 does not have default public URLs like AWS S3. Configure one of:\n1. Public bucket URL: publicUrl: 'https://pub-xxx.r2.dev'\n2. Custom domain: publicUrl: 'https://cdn.example.com'\n\nSet up public access in the Cloudflare R2 dashboard."
+      );
+    }
+    return `https://${this.resolvedConfig.bucket}.s3.${this.resolvedConfig.region}.amazonaws.com/${filePath}`;
+  }
+  /**
+   * Get storage type identifier.
+   *
+   * Returns "s3" for all S3-compatible services (AWS S3, R2, MinIO, etc.)
+   * as they all use the S3 API.
+   */
+  getType() {
+    return "s3";
+  }
+  // ============================================================
+  // Optional IStorageAdapter Methods
+  // ============================================================
+  /**
+   * Get adapter info including capabilities.
+   *
+   * @returns Adapter info with type, name, and capability flags
+   */
+  getInfo() {
+    return {
+      type: "s3",
+      name: "S3StorageAdapter",
+      supportsSignedUrls: true,
+      supportsClientUploads: true
+    };
+  }
+  /**
+   * Get file metadata from S3.
+   *
+   * Retrieves file information including size, content type, and timestamps
+   * using the HeadObject command.
+   *
+   * @param filePath - Storage path/key
+   * @returns File metadata or null if file not found
+   */
+  async getMetadata(filePath) {
+    try {
+      const command = new clientS3.HeadObjectCommand({
+        Bucket: this.resolvedConfig.bucket,
+        Key: filePath
+      });
+      const response = await this.client.send(command);
+      const filename = filePath.split("/").pop() || filePath;
+      return {
+        id: filePath,
+        filename,
+        originalFilename: response.Metadata?.["original-filename"] || filename,
+        mimeType: response.ContentType || "application/octet-stream",
+        size: response.ContentLength || 0,
+        url: this.getPublicUrl(filePath),
+        createdAt: response.LastModified?.toISOString() || (/* @__PURE__ */ new Date()).toISOString()
+      };
+    } catch (error) {
+      if (this.isNotFoundError(error)) {
+        return null;
+      }
+      throw error;
+    }
+  }
+  /**
+   * Generate signed URL for temporary private file access.
+   *
+   * Creates a pre-signed GetObject URL that grants temporary read access
+   * to private files. Useful for serving files from private buckets.
+   *
+   * @param filePath - Storage path/key
+   * @param expiresIn - URL validity duration in seconds (default: 3600)
+   * @returns Pre-signed URL for downloading the file
+   */
+  async getSignedUrl(filePath, expiresIn) {
+    const command = new clientS3.GetObjectCommand({
+      Bucket: this.resolvedConfig.bucket,
+      Key: filePath
+    });
+    return s3RequestPresigner.getSignedUrl(this.client, command, {
+      expiresIn: expiresIn ?? this.resolvedConfig.signedUrlExpiresIn
+    });
+  }
+  /**
+   * Generate pre-signed URL for client-side uploads.
+   *
+   * Creates a pre-signed PutObject URL that allows direct uploads from
+   * the browser to S3, bypassing server-side upload limits (e.g., Vercel's 4.5MB).
+   *
+   * @param key - Storage path/key for the upload
+   * @param mimeType - MIME type of the file being uploaded
+   * @param expiresIn - URL validity duration in seconds (default: 3600)
+   * @returns Client upload data with URL, method, and headers
+   */
+  async getPresignedUploadUrl(key, mimeType, expiresIn) {
+    const expiration = expiresIn ?? this.resolvedConfig.signedUrlExpiresIn;
+    const commandParams = {
+      Bucket: this.resolvedConfig.bucket,
+      Key: key,
+      ContentType: mimeType,
+      CacheControl: this.resolvedConfig.cacheControl
+    };
+    if (!this.isR2) {
+      commandParams.ACL = this.resolvedConfig.acl;
+    }
+    const command = new clientS3.PutObjectCommand(commandParams);
+    const uploadUrl = await s3RequestPresigner.getSignedUrl(this.client, command, {
+      expiresIn: expiration
+    });
+    return {
+      uploadUrl,
+      path: key,
+      method: "PUT",
+      headers: {
+        "Content-Type": mimeType
+      },
+      expiresAt: new Date(Date.now() + expiration * 1e3)
+    };
+  }
+  // ============================================================
+  // Helper Methods
+  // ============================================================
+  /**
+   * Generate a unique storage key with date-based prefix.
+   *
+   * Creates keys in format: {folder}/{year}/{month}/{uuid}-{sanitized-filename}
+   *
+   * @param filename - Original filename (will be sanitized)
+   * @param folder - Optional folder/prefix for organizing uploads
+   * @returns Generated storage key
+   */
+  generateKey(filename, folder) {
+    const sanitized = this.sanitizeFilename(filename);
+    const uuid = crypto.randomUUID();
+    const date = /* @__PURE__ */ new Date();
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, "0");
+    const prefix = folder ? `${folder}/${year}/${month}` : `${year}/${month}`;
+    return `${prefix}/${uuid}-${sanitized}`;
+  }
+  /**
+   * Sanitize filename to prevent directory traversal and S3 key issues.
+   *
+   * @param filename - Original filename
+   * @returns Sanitized filename safe for S3 keys
+   */
+  sanitizeFilename(filename) {
+    const basename = filename.split(/[/\\]/).pop() || filename;
+    return basename.replace(/[^a-zA-Z0-9._-]/g, "-");
+  }
+  /**
+   * Check if an error is a "not found" error from S3.
+   *
+   * @param error - Error to check
+   * @returns true if error indicates file not found
+   */
+  isNotFoundError(error) {
+    if (error && typeof error === "object") {
+      const e = error;
+      return e.name === "NotFound" || e.$metadata?.httpStatusCode === 404;
+    }
+    return false;
+  }
+  // ============================================================
+  // Public Accessors
+  // ============================================================
+  /**
+   * Get the S3 client instance.
+   * Useful for advanced operations not covered by the adapter interface.
+   */
+  getClient() {
+    return this.client;
+  }
+  /**
+   * Get the bucket name.
+   */
+  getBucket() {
+    return this.resolvedConfig.bucket;
+  }
+  /**
+   * Get the AWS region.
+   */
+  getRegion() {
+    return this.resolvedConfig.region;
+  }
+  /**
+   * Check if this adapter is configured for Cloudflare R2.
+   */
+  isCloudflareR2() {
+    return this.isR2;
+  }
+};
+
+// src/plugin.ts
+function s3Storage(config) {
+  if (config.enabled === false) {
+    return {
+      name: "s3-storage",
+      type: "s3",
+      collections: {},
+      adapter: null
+    };
+  }
+  const adapter = new S3StorageAdapter(config);
+  const plugin = {
+    name: "s3-storage",
+    type: "s3",
+    collections: config.collections,
+    adapter,
+    /**
+     * Generate a pre-signed URL for client-side uploads.
+     *
+     * This allows files to be uploaded directly from the browser to S3,
+     * bypassing server-side upload limits (e.g., Vercel's 4.5MB limit).
+     *
+     * @param filename - Original filename from the client
+     * @param mimeType - MIME type of the file
+     * @param collection - Collection slug this upload belongs to
+     * @returns Client upload data with pre-signed URL
+     */
+    async getClientUploadUrl(filename, mimeType, collection) {
+      const collectionConfig = config.collections[collection];
+      const prefix = typeof collectionConfig === "object" ? collectionConfig.prefix : void 0;
+      const key = generateStorageKey(filename, prefix);
+      return adapter.getPresignedUploadUrl(key, mimeType);
+    },
+    /**
+     * Generate a signed URL for private file downloads.
+     *
+     * Creates a time-limited URL for accessing files in private buckets.
+     * Only works when collection has `signedDownloads: true`.
+     *
+     * @param path - Storage path/key of the file
+     * @param expiresIn - URL validity duration in seconds
+     * @returns Signed URL for downloading the file
+     */
+    async getSignedDownloadUrl(path, expiresIn) {
+      return adapter.getSignedUrl(
+        path,
+        expiresIn ?? config.signedUrlExpiresIn ?? 3600
+      );
+    }
+  };
+  return plugin;
+}
+function generateStorageKey(filename, prefix) {
+  const sanitized = sanitizeFilename(filename);
+  const uuid = crypto.randomUUID();
+  const date = /* @__PURE__ */ new Date();
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const keyPrefix = prefix ? `${prefix}${year}/${month}` : `${year}/${month}`;
+  return `${keyPrefix}/${uuid}-${sanitized}`;
+}
+function sanitizeFilename(filename) {
+  const basename = filename.split(/[/\\]/).pop() || filename;
+  return basename.replace(/[^a-zA-Z0-9._-]/g, "-");
+}
+
+// src/index.ts
+var PACKAGE_NAME = "@nextly/storage-s3";
+var PACKAGE_VERSION = "0.1.0";
+
+exports.PACKAGE_NAME = PACKAGE_NAME;
+exports.PACKAGE_VERSION = PACKAGE_VERSION;
+exports.S3StorageAdapter = S3StorageAdapter;
+exports.s3Storage = s3Storage;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map