nextly 0.0.1 → 0.0.2-alpha.0

package/dist/_dts-chunks/image-processor.d-OO1PmMrv.d.ts

@@ -0,0 +1,335 @@
+/**
+ * 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;
+}
+interface ImageMetadata {
+    width: number;
+    height: number;
+    format: string;
+    size: number;
+}
+interface ProcessedImage {
+    buffer: Buffer;
+    metadata: ImageMetadata;
+}
+/**
+ * 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>;
+}
+
+/**
+ * Image Processor
+ *
+ * Uses Sharp for high-performance image processing:
+ * - Extract metadata (width, height, format)
+ * - Generate thumbnails (300x300, cropped to center)
+ * - Optimize images (compression, WebP conversion)
+ *
+ * Sharp is 4-5x faster than ImageMagick/GraphicsMagick
+ *
+ * NOTE: Sharp is lazy-loaded to work with Next.js serverExternalPackages
+ */
+
+declare class ImageProcessor {
+    /**
+     * Get image metadata without loading full image
+     */
+    getMetadata(buffer: Buffer): Promise<ImageMetadata>;
+    /**
+     * Generate thumbnail (300x300 by default, cropped to center)
+     *
+     * Uses "cover" fit to fill the entire 300x300 area while maintaining aspect ratio
+     */
+    generateThumbnail(buffer: Buffer, size?: number): Promise<ProcessedImage>;
+    /**
+     * Optimize image (compress, convert to WebP if beneficial)
+     *
+     * Strategy:
+     * - Small images (<100KB) and already WebP: return as-is
+     * - Otherwise: convert to WebP with quality 80
+     */
+    optimize(buffer: Buffer, quality?: number): Promise<ProcessedImage>;
+    /**
+     * Resize image to specific dimensions
+     *
+     * @param maxWidth Maximum width (maintains aspect ratio)
+     * @param maxHeight Maximum height (maintains aspect ratio)
+     */
+    resize(buffer: Buffer, maxWidth?: number, maxHeight?: number): Promise<ProcessedImage>;
+    /**
+     * Resize an image with focal point awareness and format conversion.
+     *
+     * When fit is 'cover' and a focal point is set, the crop anchors at that
+     * point instead of center. Supports format conversion ('auto' outputs webp
+     * for jpeg/png/tiff sources, keeps original for gif).
+     */
+    resizeWithFocalPoint(buffer: Buffer, options: {
+        width?: number;
+        height?: number;
+        fit: "cover" | "inside" | "contain" | "fill";
+        quality?: number;
+        format?: "auto" | "webp" | "jpeg" | "png" | "avif";
+        focalX?: number;
+        focalY?: number;
+    }): Promise<{
+        buffer: Buffer;
+        width: number;
+        height: number;
+        format: string;
+        size: number;
+    }>;
+    /**
+     * Check if buffer is a valid image
+     */
+    isValidImage(buffer: Buffer): Promise<boolean>;
+    /**
+     * Get image dimensions quickly (without full processing)
+     */
+    getDimensions(buffer: Buffer): Promise<{
+        width: number;
+        height: number;
+    } | null>;
+}
+/**
+ * Get singleton ImageProcessor instance
+ */
+declare function getImageProcessor(): ImageProcessor;
+/**
+ * Reset processor singleton (for testing)
+ */
+declare function resetImageProcessor(): void;
+
+export { ImageProcessor as g, getImageProcessor as i, resetImageProcessor as r };
+export type { BulkDeleteResult as B, CollectionStorageConfig as C, FileMetadata as F, IStorageAdapter as I, ProcessedImage as P, StoragePlugin as S, UploadOptions as U, CollectionStorageMap as a, StoragePluginConfig as b, UploadResult as c, ClientUploadData as d, StorageAdapterInfo as e, ImageMetadata as f, StorageType as h };