image-edit-tools 1.0.0

package/src/types.ts

@@ -0,0 +1,267 @@
+// ─── Input ────────────────────────────────────────────────────────────────────
+
+/**
+ * Accepted image input formats.
+ * - Buffer: raw image bytes
+ * - string starting with 'http': fetched via HTTP
+ * - string starting with 'data:': base64 data URI
+ * - string (other): treated as filesystem path
+ */
+export type ImageInput = Buffer | string;
+
+// ─── Result ───────────────────────────────────────────────────────────────────
+
+export type Ok<T> = { ok: true; data: T };
+export type Err = { ok: false; error: string; code: ErrorCode };
+export type Result<T> = Ok<T> | Err;
+export type ImageResult = Result<Buffer>;
+
+export enum ErrorCode {
+  INVALID_INPUT = 'INVALID_INPUT',
+  UNSUPPORTED_FORMAT = 'UNSUPPORTED_FORMAT',
+  OUT_OF_BOUNDS = 'OUT_OF_BOUNDS',
+  FETCH_FAILED = 'FETCH_FAILED',
+  PROCESSING_FAILED = 'PROCESSING_FAILED',
+  MODEL_NOT_FOUND = 'MODEL_NOT_FOUND',
+  TIMEOUT = 'TIMEOUT',
+}
+
+// ─── Crop ─────────────────────────────────────────────────────────────────────
+
+export type CropOptions =
+  | { mode?: 'absolute'; x: number; y: number; width: number; height: number }
+  | { mode: 'ratio'; left: number; top: number; right: number; bottom: number }
+  | { mode: 'aspect'; aspectRatio: string; anchor?: 'center' | 'top' | 'bottom' | 'face' }
+  | { mode: 'subject' };
+
+// ─── Resize ───────────────────────────────────────────────────────────────────
+
+export type ResizeFit = 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
+export type ResizeKernel = 'lanczos3' | 'nearest' | 'linear';
+
+export interface ResizeOptions {
+  width?: number;
+  height?: number;
+  scale?: number;
+  fit?: ResizeFit;
+  kernel?: ResizeKernel;
+  /** Preserve aspect ratio when only one dimension is given. Default: true */
+  withoutEnlargement?: boolean;
+}
+
+// ─── Pad ──────────────────────────────────────────────────────────────────────
+
+export interface PadOptions {
+  top?: number;
+  right?: number;
+  bottom?: number;
+  left?: number;
+  /** Square canvas shorthand: centers image and pads to this size */
+  size?: number;
+  /** CSS hex color or 'transparent'. Default: '#ffffff' */
+  color?: string;
+}
+
+// ─── Adjust ───────────────────────────────────────────────────────────────────
+
+export interface AdjustOptions {
+  /** -100 to +100 */
+  brightness?: number;
+  /** -100 to +100 */
+  contrast?: number;
+  /** -100 to +100 */
+  saturation?: number;
+  /** 0 to 360 degrees */
+  hue?: number;
+  /** 0 to 100 */
+  sharpness?: number;
+  /** -100 (cool) to +100 (warm) */
+  temperature?: number;
+}
+
+// ─── Filter ───────────────────────────────────────────────────────────────────
+
+export type FilterPreset = 'grayscale' | 'sepia' | 'invert' | 'vintage' | 'unsharp';
+
+export type FilterOptions =
+  | { preset: Exclude<FilterPreset, 'blur'> }
+  | { preset: 'blur'; radius: number };
+
+// ─── BlurRegion ───────────────────────────────────────────────────────────────
+
+export interface BlurRegion {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  /** Blur strength (sigma). Default: 10 */
+  radius?: number;
+}
+
+// ─── AddText ──────────────────────────────────────────────────────────────────
+
+export type TextAnchor =
+  | 'top-left' | 'top-center' | 'top-right'
+  | 'middle-left' | 'center' | 'middle-right'
+  | 'bottom-left' | 'bottom-center' | 'bottom-right';
+
+export interface TextBackground {
+  color: string;
+  padding?: number;
+  opacity?: number;
+  borderRadius?: number;
+}
+
+export interface TextLayer {
+  text: string;
+  x: number;
+  y: number;
+  anchor?: TextAnchor;
+  fontSize?: number;
+  fontFamily?: string;
+  /** Google Fonts URL or local file path */
+  fontUrl?: string;
+  color?: string;
+  opacity?: number;
+  align?: 'left' | 'center' | 'right';
+  /** Wrap text at this pixel width */
+  maxWidth?: number;
+  lineHeight?: number;
+  background?: TextBackground;
+}
+
+// ─── Composite ────────────────────────────────────────────────────────────────
+
+export type BlendMode = 'over' | 'multiply' | 'screen' | 'overlay' | 'darken' | 'lighten';
+
+export interface CompositeLayer {
+  image: ImageInput;
+  x?: number;
+  y?: number;
+  blend?: BlendMode;
+  opacity?: number;
+}
+
+// ─── Watermark ────────────────────────────────────────────────────────────────
+
+export type WatermarkPosition =
+  | 'top-left' | 'top-center' | 'top-right'
+  | 'center'
+  | 'bottom-left' | 'bottom-center' | 'bottom-right'
+  | 'tile';
+
+export type WatermarkOptions =
+  | {
+      type: 'text';
+      text: string;
+      position?: WatermarkPosition;
+      fontSize?: number;
+      color?: string;
+      opacity?: number;
+      tileSpacing?: number;
+    }
+  | {
+      type: 'image';
+      image: ImageInput;
+      position?: WatermarkPosition;
+      opacity?: number;
+      scale?: number;
+      tileSpacing?: number;
+    };
+
+// ─── Overlay ──────────────────────────────────────────────────────────────────
+
+export type Gravity =
+  | 'NorthWest' | 'North' | 'NorthEast'
+  | 'West' | 'Center' | 'East'
+  | 'SouthWest' | 'South' | 'SouthEast';
+
+export interface OverlayOptions {
+  gravity?: Gravity;
+  offsetX?: number;
+  offsetY?: number;
+  opacity?: number;
+  blend?: BlendMode;
+}
+
+// ─── RemoveBg ─────────────────────────────────────────────────────────────────
+
+export type RemoveBgEngine = 'onnx' | 'webai';
+
+export interface RemoveBgOptions {
+  engine?: RemoveBgEngine;
+  /** Replace transparency with this solid color instead */
+  replaceColor?: string;
+  /** Replace background with this image */
+  replaceImage?: ImageInput;
+}
+
+// ─── DetectSubject ────────────────────────────────────────────────────────────
+
+export interface BoundingBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  confidence: number;
+}
+
+// ─── Convert ──────────────────────────────────────────────────────────────────
+
+export type OutputFormat = 'jpeg' | 'png' | 'webp' | 'avif' | 'gif';
+
+export interface ConvertOptions {
+  format: OutputFormat;
+  /** 0–100. Default: 80 */
+  quality?: number;
+  /** PNG only. 0–9. Default: 6 */
+  compressionLevel?: number;
+  /** Strip all metadata. Default: true */
+  stripMetadata?: boolean;
+}
+
+// ─── Optimize ─────────────────────────────────────────────────────────────────
+
+export interface OptimizeOptions {
+  /** Target file size in KB. Quality is adjusted automatically */
+  maxSizeKB?: number;
+  /** Resize so the longest dimension does not exceed this value */
+  maxDimension?: number;
+  /** Auto-select format (WebP if alpha, JPEG otherwise). Default: true */
+  autoFormat?: boolean;
+}
+
+// ─── Metadata ─────────────────────────────────────────────────────────────────
+
+export interface ImageMetadata {
+  width: number;
+  height: number;
+  format: string;
+  fileSize: number;
+  colorSpace?: string;
+  hasAlpha: boolean;
+  channels: number;
+  density?: number;
+  exif?: Record<string, unknown>;
+}
+
+// ─── Pipeline ─────────────────────────────────────────────────────────────────
+
+export type PipelineOperation =
+  | ({ op: 'crop' } & CropOptions)
+  | ({ op: 'resize' } & ResizeOptions)
+  | ({ op: 'pad' } & PadOptions)
+  | ({ op: 'adjust' } & AdjustOptions)
+  | ({ op: 'filter' } & FilterOptions)
+  | ({ op: 'blurRegion'; regions: BlurRegion[] })
+  | ({ op: 'addText'; layers: TextLayer[] })
+  | ({ op: 'composite'; layers: CompositeLayer[] })
+  | ({ op: 'watermark' } & WatermarkOptions)
+  | ({ op: 'convert' } & ConvertOptions)
+  | ({ op: 'optimize' } & OptimizeOptions)
+  | ({ op: 'removeBg' } & RemoveBgOptions);
+
+export interface BatchOptions {
+  concurrency?: number;
+  onProgress?: (done: number, total: number) => void;
+}

package/src/utils/load-image.ts

@@ -0,0 +1,21 @@
+import { ImageInput } from '../types.js';
+import { readFile } from 'fs/promises';
+import fetch from 'node-fetch';
+
+/**
+ * Resolves any ImageInput variant to a Buffer.
+ * Handles: Buffer (passthrough), URL (fetch), base64 data URI (decode), file path (readFile).
+ */
+export async function loadImage(input: ImageInput): Promise<Buffer> {
+  if (Buffer.isBuffer(input)) return input;
+  if (input.startsWith('data:')) {
+    const base64 = input.split(',')[1];
+    return Buffer.from(base64, 'base64');
+  }
+  if (input.startsWith('http://') || input.startsWith('https://')) {
+    const res = await fetch(input);
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    return Buffer.from(await res.arrayBuffer());
+  }
+  return readFile(input);
+}

package/src/utils/result.ts

@@ -0,0 +1,4 @@
+import { Ok, Err, ErrorCode } from '../types.js'
+
+export const ok = <T>(data: T): Ok<T> => ({ ok: true, data })
+export const err = (error: string, code: ErrorCode): Err => ({ ok: false, error, code })

package/src/utils/validate.ts

@@ -0,0 +1,21 @@
+import sharp from 'sharp';
+
+/**
+ * Helper to ensure a value is a positive integer.
+ */
+export function isPositiveInt(val: any): boolean {
+  return typeof val === 'number' && Number.isInteger(val) && val > 0;
+}
+
+/**
+ * Helper to get basic dimensions securely via sharp metadata
+ */
+export async function getImageMetadata(buffer: Buffer) {
+  const metadata = await sharp(buffer).metadata();
+  return {
+    width: metadata.width ?? 0,
+    height: metadata.height ?? 0,
+    hasAlpha: metadata.hasAlpha ?? false,
+    format: metadata.format ?? 'unknown'
+  };
+}

package/tests/integration/error-handling.test.ts

@@ -0,0 +1,22 @@
+import { describe, it, expect } from 'vitest';
+import { ok, err } from '../../src/utils/result.js';
+import { ErrorCode } from '../../src/types.js';
+
+describe('error handling utilities', () => {
+  it('constructs an Ok result', () => {
+    const val = { testing: 123 };
+    const result = ok(val);
+    expect(result).toEqual({ ok: true, data: val });
+  });
+
+  it('constructs an Err result with code', () => {
+    const message = "Invalid dimensions provided";
+    const result = err(message, ErrorCode.INVALID_INPUT);
+    
+    expect(result.ok).toBe(false);
+    if (!result.ok) { // TypeScript narrowing
+      expect(result.error).toBe(message);
+      expect(result.code).toBe(ErrorCode.INVALID_INPUT);
+    }
+  });
+});

package/tests/integration/load-image.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { loadImage } from '../../src/utils/load-image.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const fixture = (name: string) => readFileSync(join(__dirname, '../fixtures', name));
+
+describe('loadImage', () => {
+  let sampleJpeg: Buffer;
+
+  beforeAll(() => {
+    sampleJpeg = fixture('sample.jpg');
+  });
+
+  it('passes through Buffer input directly', async () => {
+    const result = await loadImage(sampleJpeg);
+    expect(result).toBe(sampleJpeg);
+    expect(Buffer.isBuffer(result)).toBe(true);
+  });
+
+  it('loads image from a local file path', async () => {
+    const filePath = join(__dirname, '../fixtures/sample.jpg');
+    const result = await loadImage(filePath);
+    expect(Buffer.isBuffer(result)).toBe(true);
+    // Buffer length might be different in deep equal vs identity, but lengths should match
+    expect(result.length).toBe(sampleJpeg.length);
+  });
+
+  it('decodes a base64 data URI', async () => {
+    const base64 = `data:image/jpeg;base64,${sampleJpeg.toString('base64')}`;
+    const result = await loadImage(base64);
+    expect(Buffer.isBuffer(result)).toBe(true);
+    expect(result.length).toBe(sampleJpeg.length);
+  });
+
+  // Note: We might want to mock node-fetch for HTTP tests to avoid true network reliance,
+  // but a simple test checking if it resolves fetching an image can be mocked like so:
+  it('throws an error for invalid local paths', async () => {
+    await expect(loadImage(join(__dirname, '../fixtures/missing.jpg')))
+      .rejects.toThrow();
+  });
+});

package/tests/unit/add-text.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect, beforeAll } from 'vitest'
+import { readFileSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import { addText } from '../../src/ops/add-text.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const fixture = (name: string) => readFileSync(join(__dirname, '../fixtures', name))
+
+describe('addText', () => {
+  let sampleJpeg: Buffer
+
+  beforeAll(() => {
+    sampleJpeg = fixture('sample.jpg') // 400x300
+  })
+
+  it('adds a single text layer', async () => {
+    const result = await addText(sampleJpeg, {
+      layers: [{ text: 'Hello', x: 50, y: 50 }]
+    })
+    expect(result.ok).toBe(true)
+  })
+
+  it('adds multiple text layers with different anchors', async () => {
+    const result = await addText(sampleJpeg, {
+      layers: [
+        { text: 'Top Left', x: 10, y: 10, anchor: 'top-left' },
+        { text: 'Center', x: 200, y: 150, anchor: 'center' },
+        { text: 'Bottom Right', x: 390, y: 290, anchor: 'bottom-right' }
+      ]
+    })
+    expect(result.ok).toBe(true)
+  })
+
+  it('wraps text via maxWidth', async () => {
+    const result = await addText(sampleJpeg, {
+      layers: [{ text: 'This represents a completely long line of text that needs to wrap properly', x: 10, y: 50, maxWidth: 100 }]
+    })
+    expect(result.ok).toBe(true)
+  })
+
+  it('renders text background box', async () => {
+    const result = await addText(sampleJpeg, {
+      layers: [{ text: 'Background', x: 50, y: 50, background: { color: '#ff0000', opacity: 0.5, padding: 10, borderRadius: 5 } }]
+    })
+    expect(result.ok).toBe(true)
+  })
+
+  it('returns error if missing layers array', async () => {
+    const result = await addText(sampleJpeg, {} as any)
+    expect(result.ok).toBe(false)
+    if (result.ok) return
+    expect(result.code).toBe('INVALID_INPUT')
+  })
+})

package/tests/unit/adjust.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect, beforeAll } from 'vitest'
+import { readFileSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import { adjust } from '../../src/ops/adjust.js'
+import sharp from 'sharp'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const fixture = (name: string) => readFileSync(join(__dirname, '../fixtures', name))
+
+describe('adjust', () => {
+  let sampleJpeg: Buffer
+
+  beforeAll(() => {
+    sampleJpeg = fixture('sample.jpg') // 400x300
+  })
+
+  it('adjusts brightness', async () => {
+    const result = await adjust(sampleJpeg, { brightness: 50 })
+    expect(result.ok).toBe(true)
+  })
+
+  it('adjusts contrast', async () => {
+    const result = await adjust(sampleJpeg, { contrast: 50 })
+    expect(result.ok).toBe(true)
+  })
+
+  it('adjusts saturation', async () => {
+    const result = await adjust(sampleJpeg, { saturation: -50 })
+    expect(result.ok).toBe(true)
+  })
+
+  it('adjusts hue', async () => {
+    const result = await adjust(sampleJpeg, { hue: 180 })
+    expect(result.ok).toBe(true)
+  })
+
+  it('adjusts sharpness', async () => {
+    const result = await adjust(sampleJpeg, { sharpness: 80 })
+    expect(result.ok).toBe(true)
+  })
+
+  it('adjusts temperature (warm)', async () => {
+    const result = await adjust(sampleJpeg, { temperature: 50 })
+    expect(result.ok).toBe(true)
+  })
+
+  it('adjusts temperature (cool)', async () => {
+    const result = await adjust(sampleJpeg, { temperature: -50 })
+    expect(result.ok).toBe(true)
+  })
+
+  it('applies all adjustments together', async () => {
+    const result = await adjust(sampleJpeg, {
+      brightness: 10,
+      contrast: 10,
+      saturation: 20,
+      hue: 45,
+      sharpness: 50,
+      temperature: 10
+    })
+    expect(result.ok).toBe(true)
+  })
+
+  // ── Error paths ────────────────────────────────────────────────────────────
+
+  it('returns error for out-of-range brightness', async () => {
+    const result = await adjust(sampleJpeg, { brightness: 150 })
+    expect(result.ok).toBe(false)
+    if (result.ok) return
+    expect(result.code).toBe('INVALID_INPUT')
+  })
+
+  it('returns error for out-of-range hue', async () => {
+    const result = await adjust(sampleJpeg, { hue: -10 })
+    expect(result.ok).toBe(false)
+    if (result.ok) return
+    expect(result.code).toBe('INVALID_INPUT')
+  })
+})

package/tests/unit/batch.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect, beforeAll } from 'vitest'
+import { readFileSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import { batch } from '../../src/ops/batch.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const fixture = (name: string) => readFileSync(join(__dirname, '../fixtures', name))
+
+describe('batch', () => {
+  let sampleJpeg: Buffer
+
+  beforeAll(() => {
+    sampleJpeg = fixture('sample.jpg') 
+  })
+
+  it('processes all images', async () => {
+    const inputs = [sampleJpeg, sampleJpeg, sampleJpeg]
+    const operations: any[] = [{ op: 'resize', width: 50, height: 50 }]
+    
+    let progressUpdates = 0
+    const result = await batch(inputs, operations, {
+      concurrency: 2,
+      onProgress: (done, total) => {
+        progressUpdates++
+        expect(total).toBe(3)
+        expect(done).toBeLessThanOrEqual(3)
+      }
+    })
+    
+    expect(result).toHaveLength(3)
+    expect(progressUpdates).toBe(3)
+    for (const r of result) {
+      expect(r.ok).toBe(true)
+    }
+  })
+})

package/tests/unit/blur-region.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect, beforeAll } from 'vitest'
+import { readFileSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import { blurRegion } from '../../src/ops/blur-region.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const fixture = (name: string) => readFileSync(join(__dirname, '../fixtures', name))
+
+describe('blurRegion', () => {
+  let sampleJpeg: Buffer
+
+  beforeAll(() => {
+    sampleJpeg = fixture('sample.jpg') // 400x300
+  })
+
+  it('blurs a single region', async () => {
+    const result = await blurRegion(sampleJpeg, {
+      regions: [{ x: 50, y: 50, width: 100, height: 100, radius: 10 }]
+    })
+    expect(result.ok).toBe(true)
+  })
+
+  it('blurs multiple regions', async () => {
+    const result = await blurRegion(sampleJpeg, {
+      regions: [
+        { x: 10, y: 10, width: 50, height: 50 },
+        { x: 100, y: 100, width: 80, height: 80, radius: 5 }
+      ]
+    })
+    expect(result.ok).toBe(true)
+  })
+
+  it('fails if region is out of bounds', async () => {
+    const result = await blurRegion(sampleJpeg, {
+      regions: [{ x: 350, y: 0, width: 100, height: 100 }]
+    })
+    expect(result.ok).toBe(false)
+    if (result.ok) return
+    expect(result.code).toBe('OUT_OF_BOUNDS')
+  })
+
+  it('fails if width/height are invalid', async () => {
+    const result = await blurRegion(sampleJpeg, {
+      regions: [{ x: 0, y: 0, width: -10, height: 50 }]
+    })
+    expect(result.ok).toBe(false)
+    if (result.ok) return
+    expect(result.code).toBe('INVALID_INPUT')
+  })
+})

package/tests/unit/composite.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect, beforeAll } from 'vitest'
+import { readFileSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import { composite } from '../../src/ops/composite.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const fixture = (name: string) => readFileSync(join(__dirname, '../fixtures', name))
+
+describe('composite', () => {
+  let sampleJpeg: Buffer
+  let logoPng: Buffer
+
+  beforeAll(() => {
+    sampleJpeg = fixture('sample.jpg') // 400x300
+    logoPng = fixture('logo.png')      // 100x100
+  })
+
+  it('composites a single overlay', async () => {
+    const result = await composite(sampleJpeg, {
+      layers: [{ image: logoPng, x: 50, y: 50 }]
+    })
+    expect(result.ok).toBe(true)
+  })
+
+  it('composites multiple overlays', async () => {
+    const result = await composite(sampleJpeg, {
+      layers: [
+        { image: logoPng, x: 10, y: 10 },
+        { image: logoPng, x: 200, y: 150, blend: 'multiply' }
+      ]
+    })
+    expect(result.ok).toBe(true)
+  })
+
+  it('applies layer opacity', async () => {
+    const result = await composite(sampleJpeg, {
+      layers: [{ image: logoPng, x: 0, y: 0, opacity: 0.5 }]
+    })
+    expect(result.ok).toBe(true)
+  })
+
+  it('handles data URL as layer source', async () => {
+    const base64 = `data:image/png;base64,${logoPng.toString('base64')}`
+    const result = await composite(sampleJpeg, {
+      layers: [{ image: base64, x: 0, y: 0 }]
+    })
+    expect(result.ok).toBe(true)
+  })
+
+  it('returns error if missing layers array', async () => {
+    const result = await composite(sampleJpeg, {} as any)
+    expect(result.ok).toBe(false)
+    if (result.ok) return
+    expect(result.code).toBe('INVALID_INPUT')
+  })
+})