@nextlyhq/storage-s3 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,873 @@
+import { S3ClientConfig, S3Client } from '@aws-sdk/client-s3';
+
+/**
+ * Media Storage Types
+ *
+ * Defines interfaces and types for the unified media storage system.
+ * Supports cloud storage adapters via plugins.
+ *
+ * Storage Backends:
+ * - AWS S3 / Cloudflare R2 / MinIO (via @nextlyhq/storage-s3)
+ * - Vercel Blob (via @nextlyhq/storage-vercel-blob)
+ */
+interface UploadOptions {
+    /** Original filename from user */
+    filename: string;
+    /** MIME type (e.g., 'image/png', 'video/mp4') */
+    mimeType: string;
+    /** Optional content type override */
+    contentType?: string;
+    /** Optional folder/prefix for organizing uploads */
+    folder?: string;
+    /** Collection slug this upload belongs to (for collection-specific storage) */
+    collection?: string;
+    /** Optional Content-Disposition header value (e.g., 'attachment' for SVG security) */
+    contentDisposition?: "inline" | "attachment";
+}
+interface UploadResult {
+    /** Public URL to access the file */
+    url: string;
+    /** Storage path/key (for deletion and metadata retrieval) */
+    path: string;
+}
+/**
+ * Extended file metadata returned by getMetadata()
+ *
+ * Contains comprehensive information about an uploaded file,
+ * including dimensions for images and creation timestamps.
+ */
+interface FileMetadata {
+    /** Unique identifier (typically the storage path/key) */
+    id: string;
+    /** Storage filename (may differ from original) */
+    filename: string;
+    /** Original filename as uploaded by user */
+    originalFilename: string;
+    /** MIME type (e.g., 'image/jpeg', 'application/pdf') */
+    mimeType: string;
+    /** File size in bytes */
+    size: number;
+    /** Public URL to access the file */
+    url: string;
+    /** Thumbnail URL for images (if generated) */
+    thumbnailUrl?: string;
+    /** Image width in pixels (for images only) */
+    width?: number;
+    /** Image height in pixels (for images only) */
+    height?: number;
+    /** ISO timestamp when file was uploaded */
+    createdAt: string;
+    /** ISO timestamp when file was last modified */
+    updatedAt?: string;
+}
+/**
+ * Storage type identifier.
+ * - "s3": AWS S3 or S3-compatible services (R2, MinIO, DigitalOcean Spaces)
+ * - "vercel-blob": Vercel Blob Storage
+ * - "local": Local disk storage (default for development)
+ * - "uploadthing": Uploadthing cloud storage
+ */
+type StorageType = "s3" | "vercel-blob" | "local" | "uploadthing";
+/**
+ * Information about a storage adapter's capabilities.
+ * Returned by adapter.getInfo() method.
+ */
+interface StorageAdapterInfo {
+    /** Storage type identifier */
+    type: StorageType;
+    /** Human-readable adapter name */
+    name: string;
+    /** Whether this adapter supports signed URLs for private access */
+    supportsSignedUrls: boolean;
+    /** Whether this adapter supports client-side (direct) uploads */
+    supportsClientUploads: boolean;
+}
+/**
+ * Per-collection storage configuration.
+ * Allows customizing storage behavior for specific upload collections.
+ */
+interface CollectionStorageConfig {
+    /** Prefix/folder for this collection's uploads */
+    prefix?: string;
+    /** Enable client-side uploads (for serverless platforms with body size limits) */
+    clientUploads?: boolean;
+    /** Generate signed URLs for downloads (for private buckets) */
+    signedDownloads?: boolean;
+    /** Signed URL expiry time in seconds (default: 3600) */
+    signedUrlExpiresIn?: number;
+}
+/**
+ * Collection storage map - maps collection slugs to their config.
+ * Used in storage plugin configuration.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   media: true,  // Use default config
+ *   'private-docs': {
+ *     prefix: 'private/',
+ *     signedDownloads: true,
+ *     signedUrlExpiresIn: 900
+ *   }
+ * }
+ * ```
+ */
+type CollectionStorageMap = Record<string, boolean | CollectionStorageConfig>;
+/**
+ * Base configuration for storage plugins.
+ * Extended by specific adapter configs (S3StorageConfig, etc.)
+ */
+interface StoragePluginConfig {
+    /** Enable/disable the plugin (default: true) */
+    enabled?: boolean;
+    /** Collections to apply this storage adapter to */
+    collections: CollectionStorageMap;
+}
+/**
+ * Storage plugin returned by adapter plugin functions.
+ * These are processed during Nextly initialization.
+ *
+ * @example
+ * ```typescript
+ * // From @nextlyhq/storage-s3
+ * const plugin = s3Storage({
+ *   bucket: 'my-bucket',
+ *   region: 'us-east-1',
+ *   collections: { media: true }
+ * });
+ * // plugin implements StoragePlugin
+ * ```
+ */
+interface StoragePlugin {
+    /** Plugin name for identification */
+    name: string;
+    /** Storage type */
+    type: StorageType;
+    /** Collections this plugin handles */
+    collections: CollectionStorageMap;
+    /** The storage adapter instance */
+    adapter: IStorageAdapter;
+    /**
+     * Handler for generating client-side upload URLs.
+     * Called when clientUploads is enabled for a collection.
+     */
+    getClientUploadUrl?: (filename: string, mimeType: string, collection: string) => Promise<ClientUploadData>;
+    /**
+     * Handler for generating signed download URLs.
+     * Called when signedDownloads is enabled for a collection.
+     */
+    getSignedDownloadUrl?: (path: string, expiresIn?: number) => Promise<string>;
+}
+/**
+ * Data returned for client-side (direct) uploads.
+ * Contains pre-signed URL and headers for direct-to-storage uploads.
+ *
+ * @example
+ * ```typescript
+ * // Usage in frontend
+ * const uploadData = await fetch('/api/nextly/storage/upload-url', {
+ *   method: 'POST',
+ *   body: JSON.stringify({ filename: 'photo.jpg', mimeType: 'image/jpeg', collection: 'media' })
+ * }).then(r => r.json());
+ *
+ * // Direct upload to storage
+ * await fetch(uploadData.uploadUrl, {
+ *   method: uploadData.method,
+ *   headers: uploadData.headers,
+ *   body: file
+ * });
+ * ```
+ */
+interface ClientUploadData {
+    /** Pre-signed URL for direct upload */
+    uploadUrl: string;
+    /** Storage path/key that will be used */
+    path: string;
+    /** HTTP method to use (usually PUT for S3, POST for some services) */
+    method: "PUT" | "POST";
+    /** Headers to include in upload request */
+    headers?: Record<string, string>;
+    /** Form fields for multipart uploads (some services require this) */
+    fields?: Record<string, string>;
+    /** URL expiry timestamp */
+    expiresAt: Date;
+}
+/**
+ * Base storage adapter interface.
+ * All storage adapters must implement this interface.
+ *
+ * Core methods (required):
+ * - upload: Store file buffer
+ * - delete: Remove file from storage
+ * - exists: Check if file exists
+ * - getPublicUrl: Get public URL for file access
+ * - getType: Get storage type identifier
+ *
+ * Optional methods:
+ * - getInfo: Get adapter capabilities (recommended)
+ * - getMetadata: Retrieve file metadata
+ * - getSignedUrl: Generate temporary signed URLs for private access
+ * - getPresignedUploadUrl: Generate pre-signed URL for client uploads
+ */
+interface BulkDeleteResult {
+    successful: string[];
+    failed: Array<{
+        filePath: string;
+        error: string;
+    }>;
+}
+interface IStorageAdapter {
+    /** Upload file buffer to storage */
+    upload(buffer: Buffer, options: UploadOptions): Promise<UploadResult>;
+    /** Delete file from storage */
+    delete(filePath: string): Promise<void>;
+    /** Bulk delete files from storage. Optional — adapters that support batch operations should implement this. */
+    bulkDelete?(filePaths: string[]): Promise<BulkDeleteResult>;
+    /** Check if file exists in storage */
+    exists(filePath: string): Promise<boolean>;
+    /** Get public URL for file */
+    getPublicUrl(filePath: string): string;
+    /** Get storage type identifier */
+    getType(): string;
+    /** Read file contents from storage (optional - not all adapters support this) */
+    read?(filePath: string): Promise<Buffer | null>;
+    /** Get adapter info including capabilities (optional but recommended) */
+    getInfo?(): StorageAdapterInfo;
+    /** Get file metadata (optional - not all adapters support this) */
+    getMetadata?(filePath: string): Promise<FileMetadata | null>;
+    /** Generate signed URL for temporary private access (optional) */
+    getSignedUrl?(filePath: string, expiresIn?: number): Promise<string>;
+    /** Generate pre-signed upload URL for client-side uploads (optional) */
+    getPresignedUploadUrl?(key: string, mimeType: string, expiresIn?: number): Promise<ClientUploadData>;
+}
+
+/**
+ * S3 Storage Types
+ *
+ * Type definitions for the @nextly/storage-s3 package.
+ * Supports AWS S3 and S3-compatible services (Cloudflare R2, MinIO, DigitalOcean Spaces).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * S3 storage adapter configuration.
+ *
+ * Extends the base storage plugin config with S3-specific options.
+ * Supports AWS S3 and S3-compatible services like Cloudflare R2, MinIO, and DigitalOcean Spaces.
+ *
+ * @example AWS S3
+ * ```typescript
+ * 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
+ *   }
+ * })
+ * ```
+ *
+ * @example Cloudflare R2
+ * ```typescript
+ * 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 }
+ * })
+ * ```
+ *
+ * @example MinIO (self-hosted)
+ * ```typescript
+ * s3Storage({
+ *   bucket: 'my-bucket',
+ *   region: 'us-east-1',
+ *   accessKeyId: process.env.MINIO_ACCESS_KEY!,
+ *   secretAccessKey: process.env.MINIO_SECRET_KEY!,
+ *   endpoint: 'http://localhost:9000',
+ *   forcePathStyle: true,
+ *   collections: { media: true }
+ * })
+ * ```
+ */
+interface S3StorageConfig extends StoragePluginConfig {
+    /** Enable/disable this storage plugin (default: true). */
+    enabled?: boolean;
+    /** Collections this plugin handles. */
+    collections: Record<string, boolean | CollectionStorageConfig>;
+    /**
+     * S3 bucket name.
+     * Must be an existing bucket that the credentials have access to.
+     */
+    bucket: string;
+    /**
+     * AWS region (e.g., 'us-east-1', 'eu-west-1').
+     * Use 'auto' for Cloudflare R2.
+     */
+    region: string;
+    /**
+     * AWS SDK S3 client configuration.
+     * Use this for advanced configuration like custom retry strategies,
+     * request handlers, or middleware.
+     *
+     * Note: `region`, `endpoint`, `credentials`, and `forcePathStyle` can be
+     * specified either here or via the dedicated config properties. The dedicated
+     * properties take precedence if both are specified.
+     */
+    config?: Omit<S3ClientConfig, "region">;
+    /**
+     * AWS Access Key ID.
+     * Can also be provided via `config.credentials` or environment variables
+     * (AWS_ACCESS_KEY_ID).
+     */
+    accessKeyId?: string;
+    /**
+     * AWS Secret Access Key.
+     * Can also be provided via `config.credentials` or environment variables
+     * (AWS_SECRET_ACCESS_KEY).
+     */
+    secretAccessKey?: string;
+    /**
+     * Custom endpoint for S3-compatible services.
+     * Required for Cloudflare R2, MinIO, DigitalOcean Spaces, etc.
+     *
+     * @example Cloudflare R2
+     * ```typescript
+     * endpoint: `https://${accountId}.r2.cloudflarestorage.com`
+     * ```
+     *
+     * @example MinIO
+     * ```typescript
+     * endpoint: 'http://localhost:9000'
+     * ```
+     *
+     * @example DigitalOcean Spaces
+     * ```typescript
+     * endpoint: 'https://nyc3.digitaloceanspaces.com'
+     * ```
+     */
+    endpoint?: string;
+    /**
+     * Force path-style URLs instead of virtual-hosted-style.
+     *
+     * When true: `https://endpoint/bucket/key`
+     * When false: `https://bucket.endpoint/key`
+     *
+     * Required for MinIO and some S3-compatible services.
+     *
+     * @default false
+     */
+    forcePathStyle?: boolean;
+    /**
+     * Access Control List (ACL) for uploaded objects.
+     * Determines who can access the uploaded files.
+     *
+     * Common values:
+     * - `'private'` (default): Only authenticated users; serve via signed URLs.
+     * - `'public-read'`: Anyone can read (opt in only for buckets that
+     *   genuinely host public media).
+     * - `'bucket-owner-full-control'`: Bucket owner has full control.
+     *
+     * Defaults to `'private'` so uploads are not world-readable unless
+     * explicitly opted in. Pair with `getSignedUrl()` for read access to
+     * private objects.
+     *
+     * Note: Cloudflare R2 ignores ACL settings. Configure public access
+     * in the R2 dashboard instead.
+     *
+     * @default 'private'
+     */
+    acl?: S3ObjectACL;
+    /**
+     * Public URL override for accessing uploaded files.
+     * Use this when serving files through a CDN or custom domain.
+     *
+     * If not set, uses the standard S3 URL format:
+     * `https://{bucket}.s3.{region}.amazonaws.com/{key}`
+     *
+     * Required for Cloudflare R2 (which doesn't have default public URLs).
+     *
+     * @example CDN URL
+     * ```typescript
+     * publicUrl: 'https://cdn.example.com'
+     * ```
+     *
+     * @example R2 Public Bucket
+     * ```typescript
+     * publicUrl: 'https://pub-abc123.r2.dev'
+     * ```
+     */
+    publicUrl?: string;
+    /**
+     * Enable signed download URLs for private file access.
+     * When enabled, `getSignedUrl()` can generate temporary access URLs.
+     *
+     * Can be overridden per-collection in the collections map.
+     *
+     * @default false
+     */
+    signedDownloads?: boolean;
+    /**
+     * Default expiry time for signed URLs in seconds.
+     * Applies to both download and upload URLs.
+     *
+     * Can be overridden per-collection in the collections map.
+     *
+     * @default 3600 (1 hour)
+     */
+    signedUrlExpiresIn?: number;
+    /**
+     * Cache-Control header for uploaded files.
+     * Controls browser and CDN caching behavior.
+     *
+     * @default 'public, max-age=31536000' (1 year)
+     */
+    cacheControl?: string;
+    /**
+     * Content-Disposition header mode for uploaded files.
+     * Controls how browsers handle file downloads.
+     *
+     * - `'inline'`: Display in browser if possible
+     * - `'attachment'`: Always prompt for download
+     * - `undefined`: Don't set header (use S3/browser defaults)
+     */
+    contentDisposition?: "inline" | "attachment";
+}
+/**
+ * S3 Object Access Control List (ACL) values.
+ * Defines who can access uploaded objects.
+ *
+ * @see https://docs.aws.amazon.com/AmazonS3/latest/userguide/acl-overview.html#canned-acl
+ */
+type S3ObjectACL = "private" | "public-read" | "public-read-write" | "authenticated-read" | "aws-exec-read" | "bucket-owner-read" | "bucket-owner-full-control";
+/**
+ * S3-specific collection storage configuration.
+ * Extends base collection config with S3-specific options.
+ *
+ * @example
+ * ```typescript
+ * s3Storage({
+ *   bucket: 'my-bucket',
+ *   region: 'us-east-1',
+ *   collections: {
+ *     // Simple enable with defaults
+ *     media: true,
+ *
+ *     // Full configuration
+ *     'private-documents': {
+ *       prefix: 'docs/',
+ *       acl: 'private',
+ *       signedDownloads: true,
+ *       signedUrlExpiresIn: 900, // 15 minutes
+ *       clientUploads: true,
+ *       cacheControl: 'private, max-age=0'
+ *     }
+ *   }
+ * })
+ * ```
+ */
+interface S3CollectionConfig extends CollectionStorageConfig {
+    /**
+     * Override ACL for this collection.
+     * If not set, uses the adapter-level ACL setting.
+     */
+    acl?: S3ObjectACL;
+    /**
+     * Override Cache-Control header for this collection.
+     * If not set, uses the adapter-level cacheControl setting.
+     */
+    cacheControl?: string;
+    /**
+     * Override Content-Disposition for this collection.
+     * If not set, uses the adapter-level contentDisposition setting.
+     */
+    contentDisposition?: "inline" | "attachment";
+}
+/**
+ * Type-safe collection storage map for S3.
+ * Maps collection slugs to S3-specific configurations.
+ */
+type S3CollectionStorageMap = Record<string, boolean | S3CollectionConfig>;
+/**
+ * Resolved S3 configuration after applying defaults.
+ * Used internally by the adapter.
+ *
+ * @internal
+ */
+interface ResolvedS3Config {
+    bucket: string;
+    region: string;
+    endpoint?: string;
+    forcePathStyle: boolean;
+    acl: S3ObjectACL;
+    publicUrl?: string;
+    cacheControl: string;
+    contentDisposition?: "inline" | "attachment";
+    signedUrlExpiresIn: number;
+}
+
+/**
+ * S3 Storage Plugin
+ *
+ * Factory function that creates a storage plugin for AWS S3 and S3-compatible services.
+ * Returns a StoragePlugin that can be registered with MediaStorage.
+ *
+ * @example Basic usage with AWS S3
+ * ```typescript
+ * import { s3Storage } from '@nextly/storage-s3'
+ * import { defineConfig } from 'nextly/config'
+ *
+ * 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
+ *       }
+ *     })
+ *   ]
+ * })
+ * ```
+ *
+ * @example With Cloudflare R2
+ * ```typescript
+ * 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 }
+ * })
+ * ```
+ *
+ * @example With collection-specific configuration
+ * ```typescript
+ * s3Storage({
+ *   bucket: 'my-bucket',
+ *   region: 'us-east-1',
+ *   collections: {
+ *     // Simple enable with defaults
+ *     media: true,
+ *
+ *     // Full configuration for private documents
+ *     'private-docs': {
+ *       prefix: 'private/',
+ *       clientUploads: true,
+ *       signedDownloads: true,
+ *       signedUrlExpiresIn: 3600
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Create an S3 storage plugin for Nextly.
+ *
+ * This factory function creates a StoragePlugin that can be added to
+ * the `storage` array in `nextly.config.ts`. It supports:
+ *
+ * - AWS S3 (standard)
+ * - Cloudflare R2 (S3-compatible)
+ * - MinIO (S3-compatible, self-hosted)
+ * - DigitalOcean Spaces (S3-compatible)
+ * - Any other S3-compatible service
+ *
+ * @param config - S3 storage configuration
+ * @returns A StoragePlugin that MediaStorage can register
+ *
+ * @throws Error if bucket is not provided (via adapter)
+ * @throws Error if region is not provided (via adapter)
+ */
+declare function s3Storage(config: S3StorageConfig): StoragePlugin;
+
+/**
+ * S3 Storage Adapter
+ *
+ * Stores files on AWS S3 or S3-compatible services (Cloudflare R2, MinIO, DigitalOcean Spaces).
+ * Uses AWS SDK v3 with automatic multipart upload for large files (>5MB).
+ *
+ * Features:
+ * - Automatic multipart upload via @aws-sdk/lib-storage
+ * - Pre-signed URL generation for client-side uploads
+ * - Signed URL generation for private file access
+ * - Cloudflare R2 support (S3-compatible API)
+ * - Custom endpoint support (MinIO, DigitalOcean Spaces)
+ * - CDN URL override support
+ * - File metadata retrieval
+ *
+ * @example AWS S3
+ * ```typescript
+ * const adapter = new S3StorageAdapter({
+ *   bucket: 'my-media-bucket',
+ *   region: 'us-east-1',
+ *   accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+ *   secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+ *   collections: { media: true }
+ * });
+ * ```
+ *
+ * @example Cloudflare R2
+ * ```typescript
+ * const adapter = new S3StorageAdapter({
+ *   bucket: 'my-media',
+ *   region: 'auto',
+ *   accessKeyId: process.env.R2_ACCESS_KEY_ID!,
+ *   secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
+ *   endpoint: `https://${accountId}.r2.cloudflarestorage.com`,
+ *   publicUrl: 'https://pub-abc.r2.dev',
+ *   collections: { media: true }
+ * });
+ * ```
+ *
+ * @example MinIO (self-hosted)
+ * ```typescript
+ * const adapter = new S3StorageAdapter({
+ *   bucket: 'my-bucket',
+ *   region: 'us-east-1',
+ *   accessKeyId: process.env.MINIO_ACCESS_KEY!,
+ *   secretAccessKey: process.env.MINIO_SECRET_KEY!,
+ *   endpoint: 'http://localhost:9000',
+ *   forcePathStyle: true,
+ *   collections: { media: true }
+ * });
+ * ```
+ */
+
+/**
+ * S3 Storage Adapter
+ *
+ * Implements the IStorageAdapter interface for AWS S3 and S3-compatible services.
+ * Provides full support for uploads, downloads, signed URLs, and client-side uploads.
+ */
+declare class S3StorageAdapter implements IStorageAdapter {
+    private config;
+    private client;
+    private resolvedConfig;
+    private isR2;
+    /**
+     * Create a new S3 storage adapter.
+     *
+     * @param config - S3 storage configuration
+     * @throws Error if bucket or region is not provided
+     */
+    constructor(config: S3StorageConfig);
+    /**
+     * Build AWS credentials from config.
+     * Supports explicit credentials or falls back to SDK default chain.
+     */
+    private buildCredentials;
+    /**
+     * 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
+     */
+    upload(buffer: Buffer, options: UploadOptions): Promise<UploadResult>;
+    /**
+     * Delete file from S3.
+     *
+     * @param filePath - Storage path/key to delete
+     */
+    delete(filePath: string): Promise<void>;
+    /**
+     * 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
+     */
+    bulkDelete(filePaths: string[]): Promise<BulkDeleteResult>;
+    /**
+     * 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
+     */
+    exists(filePath: string): Promise<boolean>;
+    /**
+     * 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: string): string;
+    /**
+     * Get storage type identifier.
+     *
+     * Returns "s3" for all S3-compatible services (AWS S3, R2, MinIO, etc.)
+     * as they all use the S3 API.
+     */
+    getType(): "s3";
+    /**
+     * Get adapter info including capabilities.
+     *
+     * @returns Adapter info with type, name, and capability flags
+     */
+    getInfo(): StorageAdapterInfo;
+    /**
+     * 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
+     */
+    getMetadata(filePath: string): Promise<FileMetadata | null>;
+    /**
+     * 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
+     */
+    getSignedUrl(filePath: string, expiresIn?: number): Promise<string>;
+    /**
+     * 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
+     */
+    getPresignedUploadUrl(key: string, mimeType: string, expiresIn?: number): Promise<ClientUploadData>;
+    /**
+     * 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
+     */
+    private generateKey;
+    /**
+     * Sanitize filename to prevent directory traversal and S3 key issues.
+     *
+     * @param filename - Original filename
+     * @returns Sanitized filename safe for S3 keys
+     */
+    private sanitizeFilename;
+    /**
+     * Check if an error is a "not found" error from S3.
+     *
+     * @param error - Error to check
+     * @returns true if error indicates file not found
+     */
+    private isNotFoundError;
+    /**
+     * Get the S3 client instance.
+     * Useful for advanced operations not covered by the adapter interface.
+     */
+    getClient(): S3Client;
+    /**
+     * Get the bucket name.
+     */
+    getBucket(): string;
+    /**
+     * Get the AWS region.
+     */
+    getRegion(): string;
+    /**
+     * Check if this adapter is configured for Cloudflare R2.
+     */
+    isCloudflareR2(): boolean;
+}
+
+/**
+ * @nextly/storage-s3
+ *
+ * AWS S3 storage adapter for Nextly CMS.
+ * Also works with S3-compatible services like Cloudflare R2, MinIO, and DigitalOcean Spaces.
+ *
+ * @example Basic usage with AWS S3
+ * ```typescript
+ * import { s3Storage } from '@nextly/storage-s3'
+ * import { defineConfig } from 'nextly/config'
+ *
+ * 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
+ *       }
+ *     })
+ *   ]
+ * })
+ * ```
+ *
+ * @example With Cloudflare R2
+ * ```typescript
+ * 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 }
+ * })
+ * ```
+ *
+ * @example With MinIO
+ * ```typescript
+ * s3Storage({
+ *   bucket: 'my-bucket',
+ *   region: 'us-east-1',
+ *   accessKeyId: process.env.MINIO_ACCESS_KEY!,
+ *   secretAccessKey: process.env.MINIO_SECRET_KEY!,
+ *   endpoint: 'http://localhost:9000',
+ *   forcePathStyle: true,
+ *   collections: { media: true }
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+declare const PACKAGE_NAME = "@nextly/storage-s3";
+declare const PACKAGE_VERSION = "0.1.0";
+
+export { PACKAGE_NAME, PACKAGE_VERSION, type ResolvedS3Config, type S3CollectionConfig, type S3CollectionStorageMap, type S3ObjectACL, S3StorageAdapter, type S3StorageConfig, s3Storage };