@happyvertical/images 0.74.8

package/dist/index.d.ts

@@ -0,0 +1,218 @@
+import { ConvertOptions, GetImageProcessorOptions, HashAlgorithm, ImageDimensions, ImageInput, ImageMetadata, ResizeOptions, ThumbnailOptions } from './shared/types.js';
+/**
+ * @happyvertical/images - Image processing utilities with adapter pattern
+ *
+ * Provides a unified interface for image processing that scales from
+ * static sites to enterprise deployments:
+ *
+ * - **Sharp adapter**: Fast native processing (default)
+ * - **Jimp adapter**: Pure JavaScript fallback (serverless/edge)
+ * - **imgproxy adapter**: Self-hosted remote processing (scale)
+ *
+ * @example Basic usage with auto-detection
+ * ```typescript
+ * import { getDimensions, generateThumbnail } from '@happyvertical/images';
+ *
+ * // Automatically uses Sharp if available, falls back to Jimp
+ * const dims = await getDimensions('/path/to/image.jpg');
+ * await generateThumbnail('/path/to/image.jpg', '/path/to/thumb.jpg', {
+ *   maxWidth: 300,
+ *   maxHeight: 300
+ * });
+ * ```
+ *
+ * @example Using factory directly
+ * ```typescript
+ * import { getImageProcessor } from '@happyvertical/images';
+ *
+ * const processor = await getImageProcessor({ type: 'sharp' });
+ * const metadata = await processor.getMetadata('/path/to/image.jpg');
+ * ```
+ *
+ * @example Using imgproxy for remote processing
+ * ```typescript
+ * import { getImageProcessor } from '@happyvertical/images';
+ *
+ * const processor = await getImageProcessor({
+ *   type: 'imgproxy',
+ *   baseUrl: 'https://imgproxy.example.com',
+ *   key: 'signing-key',
+ *   salt: 'signing-salt'
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { ImgproxyAdapter, type SignedUrlOptions, signImgproxyUrl, } from './adapters/imgproxy.js';
+export { JimpAdapter } from './adapters/jimp.js';
+export { SharpAdapter } from './adapters/sharp.js';
+export { generateHeadlineCard, type HeadlineCardOptions, type HeadlineCardResult, type HeadlineCardTemplate, resetFontCache, } from './headline-card.js';
+export * from './shared/errors.js';
+export { getAvailableAdapters, getImageProcessor } from './shared/factory.js';
+export * from './shared/types.js';
+/**
+ * Reset the cached processor (useful for testing)
+ */
+export declare function resetProcessor(): void;
+/**
+ * Get image dimensions
+ *
+ * Uses auto-detection to select the best available processor.
+ *
+ * @param input - Image path or Buffer
+ * @param adapterOptions - Optional adapter configuration to override auto-detection
+ * @returns Promise resolving to image dimensions
+ *
+ * @example
+ * ```typescript
+ * import { getDimensions } from '@happyvertical/images';
+ *
+ * // Auto-detect adapter
+ * const dims = await getDimensions('/path/to/image.jpg');
+ * console.log(`${dims.width}x${dims.height}`);
+ *
+ * // Force specific adapter
+ * const jimp = await getDimensions(buffer, { type: 'jimp' });
+ * ```
+ */
+export declare function getDimensions(input: ImageInput, adapterOptions?: GetImageProcessorOptions): Promise<ImageDimensions>;
+/**
+ * Generate a thumbnail image
+ *
+ * Creates a smaller version of the image while maintaining aspect ratio.
+ * Uses auto-detection to select the best available processor.
+ *
+ * @param input - Source image path or Buffer
+ * @param output - Output file path
+ * @param options - Thumbnail options (maxWidth, maxHeight, quality, format)
+ * @param adapterOptions - Optional adapter configuration to override auto-detection
+ *
+ * @example
+ * ```typescript
+ * import { generateThumbnail } from '@happyvertical/images';
+ *
+ * // Create 300x300 max thumbnail
+ * await generateThumbnail('/path/to/image.jpg', '/path/to/thumb.jpg', {
+ *   maxWidth: 300,
+ *   maxHeight: 300,
+ *   quality: 85
+ * });
+ *
+ * // Convert to WebP while thumbnailing
+ * await generateThumbnail('/path/to/image.jpg', '/path/to/thumb.webp', {
+ *   maxWidth: 200,
+ *   format: 'webp'
+ * });
+ * ```
+ */
+export declare function generateThumbnail(input: ImageInput, output: string, options?: ThumbnailOptions, adapterOptions?: GetImageProcessorOptions): Promise<void>;
+/**
+ * Convert image format
+ *
+ * Converts an image to a different format with optional quality settings.
+ * Uses auto-detection to select the best available processor.
+ *
+ * @param input - Source image path or Buffer
+ * @param output - Output file path (format inferred from extension)
+ * @param options - Conversion options (format, quality)
+ * @param adapterOptions - Optional adapter configuration to override auto-detection
+ *
+ * @example
+ * ```typescript
+ * import { convertFormat } from '@happyvertical/images';
+ *
+ * // Convert PNG to JPEG
+ * await convertFormat('/path/to/image.png', '/path/to/image.jpg', {
+ *   quality: 90
+ * });
+ *
+ * // Convert to WebP with explicit format
+ * await convertFormat('/path/to/image.jpg', '/path/to/image.webp', {
+ *   format: 'webp',
+ *   quality: 80
+ * });
+ * ```
+ */
+export declare function convertFormat(input: ImageInput, output: string, options?: ConvertOptions, adapterOptions?: GetImageProcessorOptions): Promise<void>;
+/**
+ * Get image metadata
+ *
+ * Extracts comprehensive metadata including dimensions, format, color space,
+ * and optionally EXIF/IPTC/XMP data.
+ * Uses auto-detection to select the best available processor.
+ *
+ * @param input - Image path or Buffer
+ * @param adapterOptions - Optional adapter configuration to override auto-detection
+ * @returns Promise resolving to metadata object
+ *
+ * @example
+ * ```typescript
+ * import { getImageMetadata } from '@happyvertical/images';
+ *
+ * const metadata = await getImageMetadata('/path/to/photo.jpg');
+ * console.log(`Format: ${metadata.format}`);
+ * console.log(`Dimensions: ${metadata.width}x${metadata.height}`);
+ * console.log(`Has alpha: ${metadata.hasAlpha}`);
+ * if (metadata.exif) {
+ *   console.log('EXIF data:', metadata.exif);
+ * }
+ * ```
+ */
+export declare function getImageMetadata(input: ImageInput, adapterOptions?: GetImageProcessorOptions): Promise<ImageMetadata>;
+/**
+ * Compute image hash
+ *
+ * Generates a hash of the image for deduplication or comparison.
+ * Uses auto-detection to select the best available processor.
+ *
+ * @param input - Image path or Buffer
+ * @param algorithm - Hash algorithm: 'perceptual' (default), 'md5', 'sha256'
+ * @param adapterOptions - Optional adapter configuration to override auto-detection
+ * @returns Promise resolving to hash string
+ *
+ * @example
+ * ```typescript
+ * import { getImageHash } from '@happyvertical/images';
+ *
+ * // Perceptual hash for finding similar images
+ * const pHash = await getImageHash('/path/to/image.jpg');
+ * console.log(`Perceptual hash: ${pHash}`);
+ *
+ * // Cryptographic hash for exact matching
+ * const sha256 = await getImageHash('/path/to/image.jpg', 'sha256');
+ * console.log(`SHA-256: ${sha256}`);
+ * ```
+ */
+export declare function getImageHash(input: ImageInput, algorithm?: HashAlgorithm, adapterOptions?: GetImageProcessorOptions): Promise<string>;
+/**
+ * Resize image with full control
+ *
+ * Resizes an image to specific dimensions with control over fit mode.
+ * Uses auto-detection to select the best available processor.
+ *
+ * @param input - Source image path or Buffer
+ * @param output - Output file path
+ * @param options - Resize options (width, height, fit, quality, format)
+ * @param adapterOptions - Optional adapter configuration to override auto-detection
+ *
+ * @example
+ * ```typescript
+ * import { resizeImage } from '@happyvertical/images';
+ *
+ * // Resize to exact dimensions (may crop)
+ * await resizeImage('/path/to/image.jpg', '/path/to/resized.jpg', {
+ *   width: 800,
+ *   height: 600,
+ *   fit: 'cover' // Crop to fill
+ * });
+ *
+ * // Resize to fit within dimensions (no crop)
+ * await resizeImage('/path/to/image.jpg', '/path/to/resized.jpg', {
+ *   width: 800,
+ *   height: 600,
+ *   fit: 'inside' // Fit within, may be smaller
+ * });
+ * ```
+ */
+export declare function resizeImage(input: ImageInput, output: string, options: ResizeOptions, adapterOptions?: GetImageProcessorOptions): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,EACL,eAAe,EACf,KAAK,gBAAgB,EACrB,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EACL,oBAAoB,EACpB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,cAAc,GACf,MAAM,oBAAoB,CAAC;AAE5B,cAAc,oBAAoB,CAAC;AAEnC,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE9E,cAAc,mBAAmB,CAAC;AAElC,OAAO,KAAK,EACV,cAAc,EACd,wBAAwB,EACxB,aAAa,EACb,eAAe,EACf,UAAU,EACV,aAAa,EAEb,aAAa,EACb,gBAAgB,EACjB,MAAM,mBAAmB,CAAC;AAsD3B;;GAEG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAGrC;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,UAAU,EACjB,cAAc,CAAC,EAAE,wBAAwB,GACxC,OAAO,CAAC,eAAe,CAAC,CAG1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,gBAAgB,EAC1B,cAAc,CAAC,EAAE,wBAAwB,GACxC,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,cAAc,EACxB,cAAc,CAAC,EAAE,wBAAwB,GACxC,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,UAAU,EACjB,cAAc,CAAC,EAAE,wBAAwB,GACxC,OAAO,CAAC,aAAa,CAAC,CAGxB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,UAAU,EACjB,SAAS,GAAE,aAA4B,EACvC,cAAc,CAAC,EAAE,wBAAwB,GACxC,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,aAAa,EACtB,cAAc,CAAC,EAAE,wBAAwB,GACxC,OAAO,CAAC,IAAI,CAAC,CAGf"}