image-edit-tools 1.0.0

package/src/ops/adjust.ts

@@ -0,0 +1,68 @@
+import { AdjustOptions, ImageInput, ImageResult, ErrorCode } from '../types.js';
+import { loadImage } from '../utils/load-image.js';
+import { err, ok } from '../utils/result.js';
+import sharp from 'sharp';
+
+export async function adjust(input: ImageInput, options: AdjustOptions): Promise<ImageResult> {
+  try {
+    const buffer = await loadImage(input);
+    let pipeline = sharp(buffer);
+    
+    // Bounds checking
+    if (options.brightness !== undefined && (options.brightness < -100 || options.brightness > 100)) {
+      return err('Brightness must be between -100 and +100', ErrorCode.INVALID_INPUT);
+    }
+    if (options.contrast !== undefined && (options.contrast < -100 || options.contrast > 100)) {
+      return err('Contrast must be between -100 and +100', ErrorCode.INVALID_INPUT);
+    }
+    if (options.saturation !== undefined && (options.saturation < -100 || options.saturation > 100)) {
+      return err('Saturation must be between -100 and +100', ErrorCode.INVALID_INPUT);
+    }
+    if (options.hue !== undefined && (options.hue < 0 || options.hue > 360)) {
+      return err('Hue must be between 0 and 360', ErrorCode.INVALID_INPUT);
+    }
+    if (options.sharpness !== undefined && (options.sharpness < 0 || options.sharpness > 100)) {
+      return err('Sharpness must be between 0 and 100', ErrorCode.INVALID_INPUT);
+    }
+    if (options.temperature !== undefined && (options.temperature < -100 || options.temperature > 100)) {
+      return err('Temperature must be between -100 and +100', ErrorCode.INVALID_INPUT);
+    }
+
+    const mod: Record<string, number> = {};
+    if (options.brightness !== undefined) mod.brightness = 1 + (options.brightness / 100);
+    if (options.saturation !== undefined) mod.saturation = 1 + (options.saturation / 100);
+    if (options.hue !== undefined) mod.hue = options.hue;
+
+    if (Object.keys(mod).length > 0) pipeline = pipeline.modulate(mod);
+
+    if (options.contrast !== undefined) {
+      const c = 1 + (options.contrast / 100);
+      pipeline = pipeline.linear(c, -(128 * c) + 128);
+    }
+
+    if (options.sharpness !== undefined) {
+      const sigma = (options.sharpness / 100) * 3;
+      if (sigma > 0) pipeline = pipeline.sharpen({ sigma });
+    }
+
+    if (options.temperature !== undefined && options.temperature !== 0) {
+      const t = options.temperature;
+      let r = 255, g = 255, b = 255;
+      if (t > 0) {
+        b = Math.max(0, 255 - Math.round((t / 100) * 255));
+      } else if (t < 0) {
+        r = Math.max(0, 255 - Math.round((Math.abs(t) / 100) * 255));
+      }
+      pipeline = pipeline.tint({ r, g, b });
+    }
+
+    const output = await pipeline.toBuffer();
+    return ok(output);
+  } catch (e: any) {
+    const msg = e.message || '';
+    if (msg.includes('HTTP')) return err(msg, ErrorCode.FETCH_FAILED);
+    if (msg.includes('ENOENT')) return err('File not found', ErrorCode.INVALID_INPUT);
+    if (msg.includes('unsupported image format')) return err('Corrupt or unsupported input', ErrorCode.INVALID_INPUT);
+    return err(msg, ErrorCode.PROCESSING_FAILED);
+  }
+}

package/src/ops/batch.ts

@@ -0,0 +1,41 @@
+import { ImageInput, ImageResult, PipelineOperation, BatchOptions } from '../types.js';
+import { pipeline } from './pipeline.js';
+
+export async function batch(inputs: ImageInput[], operations: PipelineOperation[], options: BatchOptions = {}): Promise<ImageResult[]> {
+  const concurrency = options.concurrency ?? 4;
+  const results: ImageResult[] = new Array(inputs.length);
+  const queue = inputs.map((input, index) => ({ input, index }));
+  
+  let active = 0;
+  let doneCount = 0;
+  let currentIndex = 0;
+
+  return new Promise((resolve) => {
+    const checkQueue = () => {
+      if (doneCount === inputs.length) {
+        resolve(results);
+        return;
+      }
+      
+      while (active < concurrency && currentIndex < queue.length) {
+        active++;
+        const item = queue[currentIndex++];
+        
+        pipeline(item.input, operations).then((res) => {
+          results[item.index] = res;
+        }).catch((err) => {
+          results[item.index] = { ok: false, error: err.message, code: 'PROCESSING_FAILED' as any };
+        }).finally(() => {
+          active--;
+          doneCount++;
+          if (options.onProgress) {
+            options.onProgress(doneCount, inputs.length);
+          }
+          checkQueue();
+        });
+      }
+    };
+    
+    checkQueue();
+  });
+}

package/src/ops/blur-region.ts

@@ -0,0 +1,58 @@
+import sharp from 'sharp';
+import { BlurRegion, ImageInput, ImageResult, ErrorCode } from '../types.js';
+import { loadImage } from '../utils/load-image.js';
+import { err, ok } from '../utils/result.js';
+import { getImageMetadata, isPositiveInt } from '../utils/validate.js';
+
+export async function blurRegion(input: ImageInput, options: { regions: BlurRegion[] }): Promise<ImageResult> {
+  try {
+    const buffer = await loadImage(input);
+    const meta = await getImageMetadata(buffer);
+    
+    if (!options.regions || !Array.isArray(options.regions)) {
+      return err('Regions array required', ErrorCode.INVALID_INPUT);
+    }
+
+    const composites: sharp.OverlayOptions[] = [];
+
+    for (const r of options.regions) {
+      if (!isPositiveInt(r.width) || !isPositiveInt(r.height)) {
+        return err('Region dimensions must be positive integers', ErrorCode.INVALID_INPUT);
+      }
+      if (r.x < 0 || r.y < 0 || r.x + r.width > meta.width || r.y + r.height > meta.height) {
+        return err('Blur region out of bounds', ErrorCode.OUT_OF_BOUNDS);
+      }
+      
+      const radius = r.radius ?? 10;
+      if (radius <= 0) return err('Blur radius must be positive', ErrorCode.INVALID_INPUT);
+
+      const blurredRegion = await sharp(buffer)
+        .extract({ left: Math.floor(r.x), top: Math.floor(r.y), width: Math.floor(r.width), height: Math.floor(r.height) })
+        .blur(radius)
+        .toBuffer();
+
+      composites.push({
+        input: blurredRegion,
+        left: Math.floor(r.x),
+        top: Math.floor(r.y),
+        blend: 'over'
+      });
+    }
+
+    if (composites.length === 0) {
+      return ok(buffer);
+    }
+
+    const output = await sharp(buffer)
+      .composite(composites)
+      .toBuffer();
+    
+    return ok(output);
+  } catch (e: any) {
+    const msg = e.message || '';
+    if (msg.includes('HTTP')) return err(msg, ErrorCode.FETCH_FAILED);
+    if (msg.includes('ENOENT')) return err('File not found', ErrorCode.INVALID_INPUT);
+    if (msg.includes('unsupported image format')) return err('Corrupt or unsupported input', ErrorCode.INVALID_INPUT);
+    return err(msg, ErrorCode.PROCESSING_FAILED);
+  }
+}

package/src/ops/composite.ts

@@ -0,0 +1,56 @@
+import sharp from 'sharp';
+import { CompositeLayer, ImageInput, ImageResult, ErrorCode } from '../types.js';
+import { loadImage } from '../utils/load-image.js';
+import { err, ok } from '../utils/result.js';
+
+export async function composite(input: ImageInput, options: { layers: CompositeLayer[] }): Promise<ImageResult> {
+  try {
+    const buffer = await loadImage(input);
+    
+    if (!options.layers || !Array.isArray(options.layers)) {
+      return err('Layers array required', ErrorCode.INVALID_INPUT);
+    }
+
+    const loadLayer = async (layer: CompositeLayer): Promise<sharp.OverlayOptions> => {
+      let layerBuf = await loadImage(layer.image);
+      
+      if (layer.opacity !== undefined && layer.opacity >= 0 && layer.opacity < 1) {
+        layerBuf = await sharp(layerBuf)
+          .ensureAlpha()
+          .composite([
+            {
+              input: Buffer.from([255, 255, 255, Math.round(layer.opacity * 255)]),
+              raw: { width: 1, height: 1, channels: 4 },
+              tile: true,
+              blend: 'dest-in'
+            }
+          ])
+          .toBuffer();
+      }
+
+      return {
+        input: layerBuf,
+        left: layer.x !== undefined ? Math.floor(layer.x) : 0,
+        top: layer.y !== undefined ? Math.floor(layer.y) : 0,
+        blend: layer.blend || 'over'
+      };
+    };
+
+    const overlays = await Promise.all(options.layers.map(loadLayer));
+
+    let output = buffer;
+    if (overlays.length > 0) {
+      output = await sharp(buffer)
+        .composite(overlays)
+        .toBuffer();
+    }
+    
+    return ok(output);
+  } catch (e: any) {
+    const msg = e.message || '';
+    if (msg.includes('HTTP')) return err(msg, ErrorCode.FETCH_FAILED);
+    if (msg.includes('ENOENT')) return err('File not found', ErrorCode.INVALID_INPUT);
+    if (msg.includes('unsupported image format')) return err('Corrupt or unsupported input', ErrorCode.INVALID_INPUT);
+    return err(msg, ErrorCode.PROCESSING_FAILED);
+  }
+}

package/src/ops/convert.ts

@@ -0,0 +1,46 @@
+import sharp from 'sharp';
+import { ConvertOptions, ImageInput, ImageResult, ErrorCode } from '../types.js';
+import { loadImage } from '../utils/load-image.js';
+import { err, ok } from '../utils/result.js';
+
+export async function convert(input: ImageInput, options: ConvertOptions): Promise<ImageResult> {
+  try {
+    const buffer = await loadImage(input);
+    let pipeline = sharp(buffer);
+    
+    const quality = options.quality ?? 80;
+    const stripMetadata = options.stripMetadata ?? true;
+
+    if (!stripMetadata) {
+      pipeline = pipeline.keepMetadata();
+    }
+
+    switch (options.format) {
+      case 'jpeg':
+        pipeline = pipeline.jpeg({ quality });
+        break;
+      case 'png':
+        pipeline = pipeline.png({ quality, compressionLevel: options.compressionLevel ?? 6 });
+        break;
+      case 'webp':
+        pipeline = pipeline.webp({ quality });
+        break;
+      case 'avif':
+        pipeline = pipeline.avif({ quality });
+        break;
+      case 'gif':
+        pipeline = pipeline.gif(); 
+        break;
+      default:
+        return err('Unsupported format', ErrorCode.UNSUPPORTED_FORMAT);
+    }
+
+    const output = await pipeline.toBuffer();
+    return ok(output);
+  } catch (e: any) {
+    const msg = e.message || '';
+    if (msg.includes('HTTP')) return err(msg, ErrorCode.FETCH_FAILED);
+    if (msg.includes('ENOENT')) return err('File not found', ErrorCode.INVALID_INPUT);
+    return err(msg, ErrorCode.PROCESSING_FAILED);
+  }
+}

package/src/ops/crop.ts

@@ -0,0 +1,101 @@
+import sharp from 'sharp';
+import { CropOptions, ImageInput, ImageResult, ErrorCode } from '../types.js';
+import { loadImage } from '../utils/load-image.js';
+import { err, ok } from '../utils/result.js';
+import { getImageMetadata, isPositiveInt } from '../utils/validate.js';
+// import { detectSubject } from './detect-subject.js'; // Deferred for now
+
+export async function crop(input: ImageInput, options: CropOptions): Promise<ImageResult> {
+  try {
+    const buffer = await loadImage(input);
+    let meta;
+    try {
+      meta = await getImageMetadata(buffer);
+    } catch {
+      return err('Corrupt or unsupported input', ErrorCode.INVALID_INPUT);
+    }
+    
+    let left = 0, top = 0, width = meta.width, height = meta.height;
+
+    const mode = options.mode || 'absolute';
+
+    if (mode === 'absolute') {
+      const opt = options as Extract<CropOptions, { mode?: 'absolute' }>;
+      // Provide defaults if missing, theoretically
+      const optX = opt.x ?? 0;
+      const optY = opt.y ?? 0;
+      if (!isPositiveInt(opt.width) || !isPositiveInt(opt.height)) {
+        return err('Invalid dimensions', ErrorCode.INVALID_INPUT);
+      }
+      if (optX < 0 || optY < 0 || optX + opt.width > meta.width || optY + opt.height > meta.height) {
+        return err('Crop region out of bounds', ErrorCode.OUT_OF_BOUNDS);
+      }
+      left = optX;
+      top = optY;
+      width = opt.width;
+      height = opt.height;
+    } else if (mode === 'ratio') {
+      const opt = options as Extract<CropOptions, { mode: 'ratio' }>;
+      left = Math.round(meta.width * opt.left);
+      top = Math.round(meta.height * opt.top);
+      const right = Math.round(meta.width * opt.right);
+      const bottom = Math.round(meta.height * opt.bottom);
+      width = meta.width - left - right;
+      height = meta.height - top - bottom;
+      if (width <= 0 || height <= 0 || left < 0 || top < 0 || left + width > meta.width || top + height > meta.height) {
+        return err('Invalid ratio calculation out of bounds', ErrorCode.OUT_OF_BOUNDS);
+      }
+    } else if (mode === 'aspect') {
+      const opt = options as Extract<CropOptions, { mode: 'aspect' }>;
+      const [wRatio, hRatio] = opt.aspectRatio.split(':').map(Number);
+      if (!wRatio || !hRatio || wRatio <= 0 || hRatio <= 0) {
+        return err('Invalid aspect ratio format', ErrorCode.INVALID_INPUT);
+      }
+      
+      const imageRatio = meta.width / meta.height;
+      const targetRatio = wRatio / hRatio;
+      
+      if (imageRatio > targetRatio) {
+        // Target is taller/narrower: Height bounded by image height
+        height = meta.height;
+        width = Math.round(height * targetRatio);
+      } else {
+        // Target is wider/shorter: Width bounded by image width
+        width = meta.width;
+        height = Math.round(width / targetRatio);
+      }
+
+      // Handle anchor
+      const anchor = opt.anchor || 'center';
+      if (anchor === 'center') {
+        left = Math.floor((meta.width - width) / 2);
+        top = Math.floor((meta.height - height) / 2);
+      } else if (anchor === 'top') {
+        left = Math.floor((meta.width - width) / 2);
+        top = 0;
+      } else if (anchor === 'bottom') {
+        left = Math.floor((meta.width - width) / 2);
+        top = meta.height - height;
+      } else if (anchor === 'face') {
+        // Fallback for now without detectFaces
+        left = Math.floor((meta.width - width) / 2);
+        top = Math.floor((meta.height - height) / 2);
+      }
+    } else if (mode === 'subject') {
+      return err('Subject crop not currently implemented in this pass', ErrorCode.MODEL_NOT_FOUND);
+    } else {
+      return err('Invalid crop mode', ErrorCode.INVALID_INPUT);
+    }
+
+    const output = await sharp(buffer)
+      .extract({ left, top, width, height })
+      .toBuffer();
+    
+    return ok(output);
+  } catch (e: any) {
+    const msg = e.message || '';
+    if (msg.includes('HTTP')) return err(msg, ErrorCode.FETCH_FAILED);
+    if (msg.includes('ENOENT')) return err('File not found', ErrorCode.INVALID_INPUT);
+    return err(msg, ErrorCode.PROCESSING_FAILED);
+  }
+}

package/src/ops/detect-faces.ts

@@ -0,0 +1,41 @@
+import { BoundingBox, ImageInput, Result, ErrorCode } from '../types.js';
+import { loadImage } from '../utils/load-image.js';
+import { ok, err } from '../utils/result.js';
+import { pipeline, RawImage } from '@xenova/transformers';
+import sharp from 'sharp';
+
+export async function detectFaces(input: ImageInput): Promise<Result<BoundingBox[]>> {
+  try {
+    const buffer = await loadImage(input);
+    let detector: any;
+    try {
+      detector = await pipeline('object-detection', 'Xenova/detr-resnet-50', {
+        quantized: true,
+      });
+    } catch (e) {
+      return err('Model unavailable. Run: npx image-edit-tools download-models', ErrorCode.MODEL_NOT_FOUND);
+    }
+    
+    const rawRgb = await sharp(buffer).ensureAlpha().raw().toBuffer();
+    const meta = await sharp(buffer).metadata();
+    const img = new RawImage(new Uint8ClampedArray(rawRgb), meta.width!, meta.height!, 4);
+    
+    const results = await detector(img, { threshold: 0.5 });
+    const faces = results.filter((r: any) => r.label === 'person' || r.label === 'face');
+    
+    const boxes = faces.map((f: any) => ({
+      x: Math.round(f.box.xmin),
+      y: Math.round(f.box.ymin),
+      width: Math.round(f.box.xmax - f.box.xmin),
+      height: Math.round(f.box.ymax - f.box.ymin),
+      confidence: f.score
+    }));
+    
+    return ok(boxes);
+  } catch (e: any) {
+    const msg = e.message || '';
+    if (msg.includes('HTTP')) return err(msg, ErrorCode.FETCH_FAILED);
+    if (msg.includes('ENOENT')) return err('File not found', ErrorCode.INVALID_INPUT);
+    return err(msg, ErrorCode.PROCESSING_FAILED);
+  }
+}

package/src/ops/detect-subject.ts

@@ -0,0 +1,80 @@
+import { BoundingBox, ImageInput, Result, ErrorCode } from '../types.js';
+import { loadImage } from '../utils/load-image.js';
+import { err, ok } from '../utils/result.js';
+import { getImageMetadata } from '../utils/validate.js';
+import sharp from 'sharp';
+import { AutoModel, AutoProcessor, RawImage } from '@xenova/transformers';
+
+export async function detectSubject(input: ImageInput): Promise<Result<BoundingBox[]>> {
+  try {
+    const buffer = await loadImage(input);
+    const meta = await getImageMetadata(buffer);
+    
+    let model: any, processor: any;
+    try {
+      model = await AutoModel.from_pretrained('briaai/RMBG-1.4', {
+        config: { model_type: 'custom' },
+        quantized: true
+      });
+      processor = await AutoProcessor.from_pretrained('briaai/RMBG-1.4', {
+        config: {
+          do_normalize: true, do_pad: false, do_rescale: true, do_resize: true,
+          image_mean: [0.5, 0.5, 0.5], image_std: [1, 1, 1], resample: 2, size: { width: 1024, height: 1024 },
+        }
+      });
+    } catch (e: any) {
+      return err('Model unavailable. Run: npx image-edit-tools download-models', ErrorCode.MODEL_NOT_FOUND);
+    }
+
+    const rawRgb = await sharp(buffer).ensureAlpha().raw().toBuffer();
+    const img = new RawImage(new Uint8ClampedArray(rawRgb), meta.width, meta.height, 4);
+
+    const { pixel_values } = await processor(img);
+    const { output } = await model({ input: pixel_values });
+
+    const maskData = new Uint8Array(output.data.length);
+    for (let i = 0; i < output.data.length; ++i) {
+      maskData[i] = Math.max(0, Math.min(255, Math.round(output.data[i] * 255)));
+    }
+
+    const maskBuffer = await sharp(Buffer.from(maskData), { raw: { width: 1024, height: 1024, channels: 1 } })
+      .resize(meta.width, meta.height, { fit: 'fill' })
+      .raw()
+      .toBuffer();
+
+    let minX = meta.width, minY = meta.height, maxX = 0, maxY = 0;
+    let found = false;
+
+    // maskBuffer has 1 channel, size meta.width * meta.height
+    for (let y = 0; y < meta.height; y++) {
+      for (let x = 0; x < meta.width; x++) {
+        const val = maskBuffer[y * meta.width + x];
+        if (val > 128) { // Threshold for subject
+          found = true;
+          if (x < minX) minX = x;
+          if (x > maxX) maxX = x;
+          if (y < minY) minY = y;
+          if (y > maxY) maxY = y;
+        }
+      }
+    }
+
+    if (!found) {
+      return ok([]);
+    }
+
+    return ok([{
+      x: minX,
+      y: minY,
+      width: maxX - minX + 1,
+      height: maxY - minY + 1,
+      confidence: 1.0
+    }]);
+
+  } catch (e: any) {
+    const msg = e.message || '';
+    if (msg.includes('HTTP')) return err(msg, ErrorCode.FETCH_FAILED);
+    if (msg.includes('ENOENT')) return err('File not found', ErrorCode.INVALID_INPUT);
+    return err(msg, ErrorCode.PROCESSING_FAILED);
+  }
+}

package/src/ops/extract-text.ts

@@ -0,0 +1,19 @@
+import { ImageInput, Result, ErrorCode } from '../types.js';
+import { loadImage } from '../utils/load-image.js';
+import { err, ok } from '../utils/result.js';
+import Tesseract from 'tesseract.js';
+
+export async function extractText(input: ImageInput, options: { lang?: string } = {}): Promise<Result<string>> {
+  try {
+    const buffer = await loadImage(input);
+    const lang = options.lang || 'eng';
+
+    const result = await Tesseract.recognize(buffer, lang);
+    return ok(result.data.text);
+  } catch (e: any) {
+    const msg = e.message || '';
+    if (msg.includes('HTTP')) return err(msg, ErrorCode.FETCH_FAILED);
+    if (msg.includes('ENOENT')) return err('File not found', ErrorCode.INVALID_INPUT);
+    return err(msg, ErrorCode.PROCESSING_FAILED);
+  }
+}

package/src/ops/filter.ts

@@ -0,0 +1,51 @@
+import { FilterOptions, ImageInput, ImageResult, ErrorCode } from '../types.js';
+import { loadImage } from '../utils/load-image.js';
+import { err, ok } from '../utils/result.js';
+import sharp from 'sharp';
+
+export async function filter(input: ImageInput, options: FilterOptions): Promise<ImageResult> {
+  try {
+    const buffer = await loadImage(input);
+    let pipeline = sharp(buffer);
+
+    switch (options.preset) {
+      case 'grayscale':
+        pipeline = pipeline.grayscale();
+        break;
+      case 'sepia':
+        pipeline = pipeline.tint({ r: 112, g: 66, b: 20 }).modulate({ saturation: 0.5 });
+        break;
+      case 'invert':
+        pipeline = pipeline.negate();
+        break;
+      case 'vintage':
+        // vintage: grayscale -> sepia -> slight contrast reduction -> add film grain (skip grain as composite noise is complex, but we can do a slight tint instead)
+        pipeline = pipeline
+          .grayscale()
+          .tint({ r: 112, g: 66, b: 20 })
+          .modulate({ saturation: 0.8, brightness: 1.1 })
+          .linear(0.9, -(128 * 0.9) + 128);
+        break;
+      case 'unsharp':
+        pipeline = pipeline.sharpen({ sigma: 1.5, m1: 0.5, m2: 0.1 });
+        break;
+      case 'blur':
+        if (options.radius === undefined || options.radius <= 0) {
+          return err('Blur radius must be a positive number', ErrorCode.INVALID_INPUT);
+        }
+        pipeline = pipeline.blur(options.radius);
+        break;
+      default:
+        return err('Invalid filter preset', ErrorCode.INVALID_INPUT);
+    }
+
+    const output = await pipeline.toBuffer();
+    return ok(output);
+  } catch (e: any) {
+    const msg = e.message || '';
+    if (msg.includes('HTTP')) return err(msg, ErrorCode.FETCH_FAILED);
+    if (msg.includes('ENOENT')) return err('File not found', ErrorCode.INVALID_INPUT);
+    if (msg.includes('unsupported image format')) return err('Corrupt or unsupported input', ErrorCode.INVALID_INPUT);
+    return err(msg, ErrorCode.PROCESSING_FAILED);
+  }
+}

package/src/ops/get-dominant-colors.ts

@@ -0,0 +1,41 @@
+import { ImageInput, Result, ErrorCode } from '../types.js';
+import { loadImage } from '../utils/load-image.js';
+import { err, ok } from '../utils/result.js';
+import { getPaletteFromURL } from 'color-thief-node';
+import { writeFileSync, unlinkSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+export async function getDominantColors(input: ImageInput, count: number = 5): Promise<Result<string[]>> {
+  let tmpFile = '';
+  try {
+    const buffer = await loadImage(input);
+    tmpFile = join(tmpdir(), `ct-${Date.now()}-${Math.random()}.jpg`);
+    writeFileSync(tmpFile, buffer);
+
+    const palette = await getPaletteFromURL(tmpFile, count);
+    if (tmpFile) {
+        try { unlinkSync(tmpFile) } catch(e){}
+    }
+
+    const hexColors = palette.map((rgb: number[]) => {
+      return '#' + rgb.map((x: number) => x.toString(16).padStart(2, '0')).join('');
+    });
+    
+    while (hexColors.length > count) hexColors.pop();
+    while (hexColors.length > 0 && hexColors.length < count) hexColors.push(hexColors[hexColors.length - 1]);
+    
+    // If image has only 1 color and getPaletteFromURL completely fails to return array,
+    if (hexColors.length === 0) hexColors.push('#000000');
+
+    return ok(hexColors);
+  } catch (e: any) {
+    if (tmpFile) {
+        try { unlinkSync(tmpFile) } catch(e){}
+    }
+    const msg = e.message || '';
+    if (msg.includes('HTTP')) return err(msg, ErrorCode.FETCH_FAILED);
+    if (msg.includes('ENOENT')) return err('File not found', ErrorCode.INVALID_INPUT);
+    return err(msg, ErrorCode.PROCESSING_FAILED);
+  }
+}

package/src/ops/get-metadata.ts

@@ -0,0 +1,28 @@
+import sharp from 'sharp';
+import { ImageMetadata, ImageInput, Result, ErrorCode } from '../types.js';
+import { loadImage } from '../utils/load-image.js';
+import { err, ok } from '../utils/result.js';
+
+export async function getMetadata(input: ImageInput): Promise<Result<ImageMetadata>> {
+  try {
+    const buffer = await loadImage(input);
+    const meta = await sharp(buffer).metadata();
+    
+    return ok({
+      width: meta.width || 0,
+      height: meta.height || 0,
+      format: meta.format || 'unknown',
+      fileSize: meta.size || buffer.length,
+      colorSpace: meta.space,
+      hasAlpha: meta.hasAlpha || false,
+      channels: meta.channels || 3,
+      density: meta.density,
+      exif: meta.exif ? { bufferLength: meta.exif.length } : undefined
+    });
+  } catch (e: any) {
+    const msg = e.message || '';
+    if (msg.includes('HTTP')) return err(msg, ErrorCode.FETCH_FAILED);
+    if (msg.includes('ENOENT')) return err('File not found', ErrorCode.INVALID_INPUT);
+    return err(msg, ErrorCode.PROCESSING_FAILED);
+  }
+}