@allegria/aws-file-manager 1.0.1 → 1.0.3

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

@@ -0,0 +1,318 @@
+import { S3Client, StorageClass } from "@aws-sdk/client-s3";
+import type { Readable } from "stream";
+/**
+ * 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, e.g. 'us-east-1' */
+    region: string;
+    /** S3 bucket name */
+    bucketName: string;
+    /** AWS access key ID — omit to rely on environment/IAM resolution */
+    accessKeyId?: string;
+    /** AWS secret access key — omit to rely on environment/IAM resolution */
+    secretAccessKey?: string;
+    /**
+     * 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;
+    /** Signed URL TTL in seconds (default: 3600) */
+    urlExpirationSeconds?: number;
+    /** Default S3 storage class (default: INTELLIGENT_TIERING) */
+    storageClass?: StorageClass;
+}
+/**
+ * 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: Uint8Array;
+    /** 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 {
+    /**
+     * 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;
+    /**
+     * Custom filename to use instead of originalName.
+     * Used when `key` is not provided.
+     */
+    fileName?: string;
+    /**
+     * 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>;
+    /** Per-upload storage class override */
+    storageClass?: StorageClass;
+}
+/** Options for listing objects in a folder */
+export interface ListOptions {
+    /** Folder path appended to basePath */
+    folder?: string;
+    /** Additional prefix filter within the folder */
+    prefix?: string;
+    /** Maximum number of keys to return (1–1000, default: 1000) */
+    maxResults?: number;
+    /** Continuation token from a previous list call for pagination */
+    continuationToken?: string;
+}
+/** 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;
+    /** 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;
+    /** 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;
+}
+/** Paginated result from list() */
+export interface ListResult {
+    entries: ListEntry[];
+    /** Pass this to the next list() call to fetch the next page */
+    continuationToken?: string;
+    /** 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: ObjectMetadata;
+} : {
+    stream: Readable;
+    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;
+/**
+ * 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 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);
+    /**
+     * 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;
+     */
+    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>;
+    /**
+     * Deletes multiple objects in a single call.
+     * Silently skips keys that do not exist.
+     *
+     * @example
+     * await fileManager.deleteMany([original.s3Key, thumbnail.s3Key]);
+     */
+    deleteMany(keys: string[]): Promise<void>;
+    /**
+     * 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);
+     */
+    copy(sourceKey: string, destinationKey: string, options?: {
+        storageClass?: StorageClass;
+        metadata?: Record<string, string>;
+    }): Promise<void>;
+    /**
+     * 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);
+     */
+    list(options?: ListOptions): Promise<ListResult>;
+    /**
+     * 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');
+     * }
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * 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;
+}