@allegria/aws-file-manager 0.0.1 → 1.0.2

package/dist/lib/aws-file-manager.d.ts

@@ -1,158 +1,318 @@
 import { S3Client, StorageClass } from "@aws-sdk/client-s3";
 import type { Readable } from "stream";
 /**
- * Configuration options for the AWS File Manager
+ * Configuration options for AwsFileManager.
+ * Credentials are optional — when omitted, the SDK resolves them from the
+ * environment (IAM role, AWS_ACCESS_KEY_ID, ~/.aws/credentials, etc.).
+ * Prefer environment/IAM resolution in production.
  */
 export interface AwsFileManagerConfig {
-    /** AWS region */
+    /** AWS region, e.g. 'us-east-1' */
     region: string;
     /** S3 bucket name */
     bucketName: string;
-    /** AWS access key ID (optional if using environment variables) */
+    /** AWS access key ID — omit to rely on environment/IAM resolution */
     accessKeyId?: string;
-    /** AWS secret access key (optional if using environment variables) */
+    /** AWS secret access key — omit to rely on environment/IAM resolution */
     secretAccessKey?: string;
-    /** Default S3 ACL ('private', 'public-read', etc.) (default: 'private') */
-    acl?: string;
-    /** Base folder path in the bucket (default: '') */
+    /**
+     * Base path prefix prepended to every key (no leading/trailing slashes).
+     * Useful for namespacing all writes to a sub-folder, e.g. 'uploads'.
+     */
     basePath?: string;
-    /** URL expiration time in seconds for signed URLs (default: 3600) */
+    /** Signed URL TTL in seconds (default: 3600) */
     urlExpirationSeconds?: number;
-    /** Default storage class for uploaded files (default: 'STANDARD') */
+    /** Default S3 storage class (default: INTELLIGENT_TIERING) */
     storageClass?: StorageClass;
 }
 /**
- * Options for uploading a file to S3
+ * A normalised file input that works for both server-side (multer Buffer) and
+ * browser-side (Web API File) callers. Use `fromMullerFile()` or
+ * `fromWebFile()` helpers to construct one, or build it directly.
  */
+export interface FileInput {
+    /** Raw file bytes */
+    buffer: Buffer;
+    /** Original filename as provided by the uploader */
+    originalName: string;
+    /** MIME type, e.g. 'image/jpeg' */
+    mimeType: string;
+    /** File size in bytes */
+    size: number;
+}
+/** Options that control how a single file is stored in S3. */
 export interface UploadOptions {
-    /** Folder path in the bucket (appended to basePath) */
+    /**
+     * Full S3 key (path + filename) for this object, relative to basePath.
+     * When provided, `folder` and `generateUniqueFileName` are ignored.
+     * Prefer this in pipeline usage where the calling code owns key generation.
+     */
+    key?: string;
+    /**
+     * Folder path appended to basePath (no leading/trailing slashes).
+     * Used when `key` is not provided.
+     */
     folder?: string;
-    /** Override the file's content type */
-    contentType?: string;
-    /** Override the default ACL */
-    acl?: string;
-    /** Custom file name */
+    /**
+     * Custom filename to use instead of originalName.
+     * Used when `key` is not provided.
+     */
     fileName?: string;
-    generateFileName?: boolean;
-    /** Additional metadata for the file */
+    /**
+     * When true and `key` is not provided, replaces the filename with a UUID
+     * while preserving the extension. Prevents collisions under concurrent
+     * uploads.
+     */
+    generateUniqueFileName?: boolean;
+    /** Override the detected MIME type */
+    contentType?: string;
+    /** Arbitrary string metadata stored alongside the S3 object */
     metadata?: Record<string, string>;
-    /** S3 storage class for the file */
+    /** Per-upload storage class override */
     storageClass?: StorageClass;
 }
-/**
- * Options for finding files in S3
- */
-export interface FindOptions {
-    /** Folder path to search in (appended to basePath) */
+/** Options for listing objects in a folder */
+export interface ListOptions {
+    /** Folder path appended to basePath */
     folder?: string;
-    /** Maximum number of results to return */
+    /** Additional prefix filter within the folder */
+    prefix?: string;
+    /** Maximum number of keys to return (1–1000, default: 1000) */
     maxResults?: number;
-    /** Continuation token for pagination */
+    /** Continuation token from a previous list call for pagination */
     continuationToken?: string;
-    /** Filter by file prefix */
-    prefix?: string;
-    /** Generate signed URLs for the files */
-    generateUrls?: boolean;
 }
-/**
- * Result of a successful S3 upload
- */
-export interface FileResult {
-    /** The S3 object key */
+/** Options for generating a signed URL for an existing key */
+export interface SignedUrlOptions {
+    /** TTL override in seconds. Falls back to instance default. */
+    expiresIn?: number;
+    /**
+     * Sets Content-Disposition on the response.
+     * 'inline' — browser renders the file (images, PDFs).
+     * 'attachment' — browser downloads the file.
+     */
+    disposition?: "inline" | "attachment";
+    /** Original filename to suggest in Content-Disposition (for attachments) */
+    fileName?: string;
+}
+/** Metadata returned after a successful upload */
+export interface UploadResult {
+    /** Full S3 key for this object — store this in your database */
     key: string;
-    /** The URL of the file (signed or public depending on ACL) */
-    url: string;
-    /** The file name */
-    fileName: string;
-    /** The original file name (for uploads) */
-    originalName?: string;
-    /** The file size in bytes */
-    size?: number;
-    /** The file's MIME type */
-    contentType?: string;
-    /** The ETag from S3 */
+    /** Original filename as provided by the uploader */
+    originalName: string;
+    /** Filename used in S3 (may differ from originalName if UUID was generated) */
+    storedName: string;
+    /** Stored file size in bytes */
+    size: number;
+    /** MIME type */
+    contentType: string;
+    /** S3 ETag (without surrounding quotes) */
     etag?: string;
-    /** Last modified date */
-    lastModified?: Date;
-    /** Additional metadata */
-    metadata?: Record<string, string>;
-    /** Storage class of the file */
+    /** Storage class applied */
+    storageClass: string;
+}
+/** A single entry returned by list() */
+export interface ListEntry {
+    /** Full S3 key */
+    key: string;
+    /** Filename portion of the key */
+    fileName: string;
+    /** Object size in bytes */
+    size: number;
+    /** Last modified timestamp */
+    lastModified: Date;
+    /** Storage class */
     storageClass?: string;
+    /** ETag (without surrounding quotes) */
+    etag?: string;
 }
-/**
- * Result of a find operation
- */
-export interface FindResult {
-    /** List of files found */
-    files: FileResult[];
-    /** Continuation token for pagination */
+/** Paginated result from list() */
+export interface ListResult {
+    entries: ListEntry[];
+    /** Pass this to the next list() call to fetch the next page */
     continuationToken?: string;
-    /** Whether there are more results */
+    /** True when there are more results beyond this page */
     hasMore: boolean;
 }
 export type DownloadMode = "buffer" | "stream";
 export type DownloadResult<T extends DownloadMode> = T extends "buffer" ? {
     buffer: Buffer;
-    metadata: Record<string, any>;
+    metadata: ObjectMetadata;
 } : {
     stream: Readable;
-    metadata: Record<string, any>;
+    metadata: ObjectMetadata;
 };
+export interface ObjectMetadata {
+    contentType?: string;
+    contentLength?: number;
+    lastModified?: Date;
+    metadata?: Record<string, string>;
+    storageClass?: string;
+}
+/**
+ * Adapts a multer file (Express.Multer.File) to FileInput.
+ *
+ * @example
+ * // In an Express route with multer:
+ * const fileInput = fromMulterFile(req.file);
+ */
+export declare function fromMulterFile(multerFile: {
+    buffer: Buffer;
+    originalname: string;
+    mimetype: string;
+    size: number;
+}): FileInput;
 /**
- * AWS File Manager class for handling S3 file operations
+ * Adapts a Web API File (browser / Next.js App Router FormData) to FileInput.
+ *
+ * @example
+ * // In a Next.js App Router route handler:
+ * const formData = await request.formData();
+ * const fileInput = await fromWebFile(formData.get('file') as File);
  */
-export default class AwsFileManager {
-    private s3Client;
-    private bucketName;
-    private acl;
-    private basePath;
-    private urlExpirationSeconds;
-    private storageClass;
-    static DEFAULTS: {
-        storageClass: "INTELLIGENT_TIERING";
-        urlExpirationSeconds: number;
+export declare function fromWebFile(webFile: File): Promise<FileInput>;
+export declare class AwsFileManager {
+    private readonly s3;
+    private readonly bucketName;
+    private readonly basePath;
+    private readonly urlExpirationSeconds;
+    private readonly storageClass;
+    static readonly DEFAULTS: {
+        readonly storageClass: "INTELLIGENT_TIERING";
+        readonly urlExpirationSeconds: 3600;
     };
+    constructor(config: AwsFileManagerConfig);
     /**
-     * Creates a new AWS File Manager instance
-     * @param config - Configuration options
+     * Uploads a file to S3 and returns storage metadata (no URL).
+     *
+     * The returned `key` is what you persist to your database. Generate signed
+     * URLs on demand via `getSignedUrl()` — never store them, as they expire.
+     *
+     * @example
+     * // In a pipeline step:
+     * const result = await fileManager.upload(ctx.fileInput, { key: ctx.s3Key });
+     * ctx.uploadResult = result;
      */
-    constructor(config: AwsFileManagerConfig);
+    upload(file: FileInput, options?: UploadOptions): Promise<UploadResult>;
+    /**
+     * Generates a short-lived signed URL for a private S3 object.
+     *
+     * Call this at request time; never store the returned URL. Signed URLs
+     * are credentials — treat them accordingly.
+     *
+     * @example
+     * const url = await fileManager.getSignedUrl(file.s3Key, {
+     *   disposition: 'inline',
+     *   fileName: file.originalName,
+     * });
+     */
+    getSignedUrl(key: string, options?: SignedUrlOptions): Promise<string>;
+    /**
+     * Downloads an S3 object as a Buffer or a Node.js Readable stream.
+     *
+     * Use `'stream'` (default) when piping to a response or writing to disk.
+     * Use `'buffer'` when you need the full bytes in memory (e.g. for processing).
+     *
+     * Returns `null` when the object does not exist.
+     *
+     * @example
+     * const result = await fileManager.download(key, 'buffer');
+     * if (result) {
+     *   const { buffer, metadata } = result;
+     * }
+     */
+    download<T extends DownloadMode = "stream">(key: string, mode?: T): Promise<DownloadResult<T> | null>;
+    /**
+     * Permanently deletes an object from S3.
+     *
+     * Note: this only removes the S3 object. Your database record should be
+     * soft-deleted first, and this called as a cleanup step after the DB
+     * transaction commits — so a crash mid-way leaves a recoverable orphan
+     * rather than a missing file with an intact DB row.
+     *
+     * @example
+     * await fileManager.delete(file.s3Key);
+     */
+    delete(key: string): Promise<void>;
     /**
-     * Generates a full S3 key including the base path and folder
-     * @param fileName - The file name
-     * @param folder - Optional folder path
-     * @returns Full S3 key
+     * Deletes multiple objects in a single call.
+     * Silently skips keys that do not exist.
+     *
+     * @example
+     * await fileManager.deleteMany([original.s3Key, thumbnail.s3Key]);
      */
-    private getFullKey;
+    deleteMany(keys: string[]): Promise<void>;
     /**
-     * Generates a file name for S3
-     * @param originalName - The original file name
-     * @param customName - Optional custom file name
-     * @returns Generated file name
+     * Copies an object within the same bucket.
+     *
+     * Useful when duplicating files across entities (e.g. cloning a note)
+     * or reorganising keys without re-uploading bytes.
+     *
+     * @example
+     * await fileManager.copy(sourceFile.s3Key, newKey);
      */
-    private generateFileName;
+    copy(sourceKey: string, destinationKey: string, options?: {
+        storageClass?: StorageClass;
+        metadata?: Record<string, string>;
+    }): Promise<void>;
     /**
-     * Uploads a single file to S3
-     * @param file - The file to upload (Buffer or Multer file)
-     * @param options - Upload options
-     * @returns Upload result
+     * Lists objects under a folder prefix.
+     *
+     * Results are paginated. Pass the returned `continuationToken` back
+     * into subsequent calls to walk through large result sets.
+     *
+     * Primarily intended for the server-side storage reconciliation job
+     * (nightly scan to reconcile DB byte counts against S3 actuals).
+     *
+     * @example
+     * let token: string | undefined;
+     * do {
+     *   const result = await fileManager.list({ folder: 'acme-corp', continuationToken: token });
+     *   processBatch(result.entries);
+     *   token = result.continuationToken;
+     * } while (result.hasMore);
      */
-    upload(file: File, options?: UploadOptions): Promise<FileResult>;
+    list(options?: ListOptions): Promise<ListResult>;
     /**
-     * Downloads a file from S3
-     * @param key - The S3 object key
-     * @returns File buffer and metadata or null if not found
+     * Returns true if an object exists at the given key.
+     *
+     * @example
+     * if (!(await fileManager.exists(key))) {
+     *   throw new Error('Referenced file is missing from storage');
+     * }
      */
-    download<T extends DownloadMode = "stream">(key: string, mode?: T): Promise<{
-        buffer: Buffer;
-        metadata: Record<string, any>;
-    } | {
-        stream: Readable;
-        metadata: Record<string, any>;
-    } | null>;
+    exists(key: string): Promise<boolean>;
     /**
-     * Gets the S3 client instance
-     * @returns S3 client
+     * Returns the underlying S3Client for operations not covered by this class.
+     * Use sparingly — prefer adding methods here so the abstraction stays coherent.
      */
     getS3Client(): S3Client;
+    /**
+     * Resolves the final S3 key and stored filename from upload options.
+     *
+     * Priority order for the key:
+     *   1. options.key (explicit full key — pipeline usage)
+     *   2. basePath + folder + fileName (if provided)
+     *   3. basePath + folder + UUID-based name (if generateUniqueFileName)
+     *   4. basePath + folder + originalName (fallback)
+     */
+    private resolveKey;
+    /**
+     * Builds a full S3 key from basePath, optional folder, and filename.
+     */
+    private buildFullKey;
+    /**
+     * Builds a prefix string for list operations.
+     */
+    private buildPrefix;
+    /**
+     * Generates a UUID-based filename, preserving the original extension.
+     * UUIDs are collision-proof under any upload concurrency.
+     */
+    private makeUniqueFileName;
+    /**
+     * Builds a Content-Disposition header value from SignedUrlOptions.
+     */
+    private buildContentDisposition;
 }