image-edit-tools 1.0.4 → 1.0.6

package/src/ops/draw-shape.ts

@@ -0,0 +1,58 @@
+import sharp from 'sharp';
+import { DrawShapeOptions, ImageResult, ErrorCode } from '../types.js';
+import { err, ok } from '../utils/result.js';
+
+export async function drawShape(options: DrawShapeOptions): Promise<ImageResult> {
+  try {
+    const { width, height, shape } = options;
+    const fill = options.fill ?? 'transparent';
+    const fillOpacity = options.fillOpacity ?? 1;
+    const stroke = options.stroke ?? 'none';
+    const strokeWidth = options.strokeWidth ?? 0;
+    const borderRadius = options.borderRadius ?? 0;
+
+    let shapeEl: string;
+
+    switch (shape) {
+      case 'rect': {
+        shapeEl = `<rect x="${strokeWidth / 2}" y="${strokeWidth / 2}" width="${width - strokeWidth}" height="${height - strokeWidth}" rx="${borderRadius}" ry="${borderRadius}" fill="${fill}" fill-opacity="${fillOpacity}" stroke="${stroke}" stroke-width="${strokeWidth}"/>`;
+        break;
+      }
+      case 'circle': {
+        const cx = options.cx ?? width / 2;
+        const cy = options.cy ?? height / 2;
+        const r = options.r ?? Math.min(width, height) / 2 - strokeWidth;
+        shapeEl = `<circle cx="${cx}" cy="${cy}" r="${r}" fill="${fill}" fill-opacity="${fillOpacity}" stroke="${stroke}" stroke-width="${strokeWidth}"/>`;
+        break;
+      }
+      case 'ellipse': {
+        const cx = options.cx ?? width / 2;
+        const cy = options.cy ?? height / 2;
+        const rx = options.r ?? width / 2 - strokeWidth;
+        const ry = options.ry ?? height / 2 - strokeWidth;
+        shapeEl = `<ellipse cx="${cx}" cy="${cy}" rx="${rx}" ry="${ry}" fill="${fill}" fill-opacity="${fillOpacity}" stroke="${stroke}" stroke-width="${strokeWidth}"/>`;
+        break;
+      }
+      case 'line': {
+        const x1 = options.x1 ?? 0;
+        const y1 = options.y1 ?? 0;
+        const x2 = options.x2 ?? width;
+        const y2 = options.y2 ?? height;
+        shapeEl = `<line x1="${x1}" y1="${y1}" x2="${x2}" y2="${y2}" stroke="${stroke || fill}" stroke-width="${strokeWidth || 2}"/>`;
+        break;
+      }
+      default:
+        return err(`Unknown shape: ${shape}`, ErrorCode.INVALID_INPUT);
+    }
+
+    const svg = `<svg width="${width}" height="${height}" xmlns="http://www.w3.org/2000/svg">${shapeEl}</svg>`;
+
+    const output = await sharp(Buffer.from(svg))
+      .png()
+      .toBuffer();
+
+    return ok(output);
+  } catch (e: any) {
+    return err(e.message || 'Draw shape failed', ErrorCode.PROCESSING_FAILED);
+  }
+}

package/src/ops/drop-shadow.ts

@@ -0,0 +1,60 @@
+import sharp from 'sharp';
+import { DropShadowOptions, ImageInput, ImageResult, ErrorCode } from '../types.js';
+import { loadImage } from '../utils/load-image.js';
+import { err, ok } from '../utils/result.js';
+import { getImageMetadata } from '../utils/validate.js';
+
+export async function dropShadow(input: ImageInput, options: DropShadowOptions = {}): Promise<ImageResult> {
+  try {
+    const buffer = await loadImage(input);
+    const meta = await getImageMetadata(buffer);
+    const { width, height } = meta;
+
+    const offsetX = options.offsetX ?? 4;
+    const offsetY = options.offsetY ?? 4;
+    const blurRadius = options.blur ?? 8;
+    const color = options.color ?? 'rgba(0,0,0,0.5)';
+    const expand = options.expand ?? true;
+
+    const expandPx = expand ? Math.ceil(blurRadius * 2 + Math.max(Math.abs(offsetX), Math.abs(offsetY))) : 0;
+    const canvasW = width + expandPx * 2;
+    const canvasH = height + expandPx * 2;
+
+    // Create shadow by making a silhouette of the source image
+    const silhouette = await sharp(buffer)
+      .ensureAlpha()
+      .png()
+      .toBuffer();
+
+    // Tint to create a colored, blurred shadow
+    const shadow = await sharp({
+      create: { width, height, channels: 4, background: color }
+    })
+      .png()
+      .toBuffer();
+
+    // Use source alpha as mask for the shadow color
+    const maskedShadow = await sharp(shadow)
+      .composite([{
+        input: silhouette,
+        blend: 'dest-in'
+      }])
+      .blur(Math.max(0.3, blurRadius))
+      .toBuffer();
+
+    // Assemble on canvas
+    const canvas = await sharp({
+      create: { width: canvasW, height: canvasH, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 0 } }
+    })
+      .composite([
+        { input: maskedShadow, left: expandPx + offsetX, top: expandPx + offsetY, blend: 'over' },
+        { input: buffer, left: expandPx, top: expandPx, blend: 'over' }
+      ])
+      .png()
+      .toBuffer();
+
+    return ok(canvas);
+  } catch (e: any) {
+    return err(e.message || 'Drop shadow failed', ErrorCode.PROCESSING_FAILED);
+  }
+}

package/src/ops/gradient-overlay.ts

@@ -0,0 +1,62 @@
+import sharp from 'sharp';
+import { GradientOverlayOptions, ImageInput, ImageResult, ErrorCode } from '../types.js';
+import { loadImage } from '../utils/load-image.js';
+import { err, ok } from '../utils/result.js';
+import { getImageMetadata } from '../utils/validate.js';
+
+function buildGradientSvg(
+  width: number,
+  height: number,
+  direction: string,
+  color: string,
+  opacity: number,
+  coverage: number
+): string {
+  // Map direction to SVG linearGradient coordinates
+  const dirMap: Record<string, { x1: string; y1: string; x2: string; y2: string }> = {
+    'top':          { x1: '0%', y1: '0%',   x2: '0%', y2: '100%' },
+    'bottom':       { x1: '0%', y1: '100%', x2: '0%', y2: '0%' },
+    'left':         { x1: '0%', y1: '0%',   x2: '100%', y2: '0%' },
+    'right':        { x1: '100%', y1: '0%', x2: '0%', y2: '0%' },
+    'top-left':     { x1: '0%', y1: '0%',   x2: '100%', y2: '100%' },
+    'top-right':    { x1: '100%', y1: '0%', x2: '0%', y2: '100%' },
+    'bottom-left':  { x1: '0%', y1: '100%', x2: '100%', y2: '0%' },
+    'bottom-right': { x1: '100%', y1: '100%', x2: '0%', y2: '0%' },
+  };
+
+  const d = dirMap[direction] ?? dirMap['bottom'];
+  const stopOffset = Math.round(coverage * 100);
+
+  return `<svg width="${width}" height="${height}" xmlns="http://www.w3.org/2000/svg">
+    <defs>
+      <linearGradient id="g" x1="${d.x1}" y1="${d.y1}" x2="${d.x2}" y2="${d.y2}">
+        <stop offset="0%" stop-color="${color}" stop-opacity="${opacity}"/>
+        <stop offset="${stopOffset}%" stop-color="${color}" stop-opacity="0"/>
+      </linearGradient>
+    </defs>
+    <rect width="${width}" height="${height}" fill="url(#g)"/>
+  </svg>`;
+}
+
+export async function gradientOverlay(input: ImageInput, options: GradientOverlayOptions = {}): Promise<ImageResult> {
+  try {
+    const buffer = await loadImage(input);
+    const meta = await getImageMetadata(buffer);
+    const { width, height } = meta;
+
+    const direction = options.direction ?? 'bottom';
+    const color = options.color ?? '#000000';
+    const opacity = options.opacity ?? 0.7;
+    const coverage = options.coverage ?? 0.5;
+
+    const svg = buildGradientSvg(width, height, direction, color, opacity, coverage);
+
+    const output = await sharp(buffer)
+      .composite([{ input: Buffer.from(svg), blend: 'over' }])
+      .toBuffer();
+
+    return ok(output);
+  } catch (e: any) {
+    return err(e.message || 'Gradient overlay failed', ErrorCode.PROCESSING_FAILED);
+  }
+}

package/src/ops/pipeline.ts

@@ -10,6 +10,10 @@ import { composite } from './composite.js';
 import { watermark } from './watermark.js';
 import { convert } from './convert.js';
 import { optimize } from './optimize.js';
+import { rotate } from './rotate.js';
+import { gradientOverlay } from './gradient-overlay.js';
+import { clipToShape } from './clip-to-shape.js';
+import { dropShadow } from './drop-shadow.js';
 
 export async function pipeline(input: ImageInput, operations: PipelineOperation[]): Promise<ImageResult & { step?: number }> {
   let currentImage = input;
@@ -31,6 +35,10 @@ export async function pipeline(input: ImageInput, operations: PipelineOperation[
         case 'watermark': result = await watermark(currentImage, op); break;
         case 'convert': result = await convert(currentImage, op); break;
         case 'optimize': result = await optimize(currentImage, op); break;
+        case 'rotate': result = await rotate(currentImage, op); break;
+        case 'gradientOverlay': result = await gradientOverlay(currentImage, op); break;
+        case 'clipToShape': result = await clipToShape(currentImage, op); break;
+        case 'dropShadow': result = await dropShadow(currentImage, op); break;
         case 'removeBg': {
           const { removeBg } = await import('./remove-bg.js');
           result = await removeBg(currentImage, op);
@@ -62,3 +70,4 @@ export async function pipeline(input: ImageInput, operations: PipelineOperation[
 
   return { ok: true, data: currentImage as Buffer };
 }
+

package/src/ops/rotate.ts

@@ -0,0 +1,27 @@
+import sharp from 'sharp';
+import { RotateOptions, ImageInput, ImageResult, ErrorCode } from '../types.js';
+import { loadImage } from '../utils/load-image.js';
+import { err, ok } from '../utils/result.js';
+
+export async function rotate(input: ImageInput, options: RotateOptions): Promise<ImageResult> {
+  try {
+    const buffer = await loadImage(input);
+    const angle = options.angle % 360;
+
+    if (angle === 0) return ok(buffer);
+
+    const bgColor = options.background ?? { r: 0, g: 0, b: 0, alpha: 0 };
+    const background = typeof bgColor === 'string'
+      ? bgColor
+      : bgColor;
+
+    const output = await sharp(buffer)
+      .rotate(angle, { background })
+      .png()
+      .toBuffer();
+
+    return ok(output);
+  } catch (e: any) {
+    return err(e.message || 'Rotation failed', ErrorCode.PROCESSING_FAILED);
+  }
+}

package/src/types.ts

@@ -128,6 +128,12 @@ export interface TextLayer {
   maxWidth?: number;
   lineHeight?: number;
   background?: TextBackground;
+  /** Letter spacing in pixels. Default: 0 */
+  letterSpacing?: number;
+  /** Text stroke (outline) */
+  stroke?: { color: string; width: number };
+  /** Text shadow */
+  textShadow?: { color: string; offsetX: number; offsetY: number; blur?: number };
 }
 
 // ─── Composite ────────────────────────────────────────────────────────────────
@@ -245,6 +251,94 @@ export interface ImageMetadata {
   exif?: Record<string, unknown>;
 }
 
+// ─── Rotate ───────────────────────────────────────────────────────────────────
+
+export interface RotateOptions {
+  /** Rotation angle in degrees (0–360). Positive = clockwise. */
+  angle: number;
+  /** Background color for exposed areas. Default: 'transparent' */
+  background?: string;
+}
+
+// ─── GradientOverlay ──────────────────────────────────────────────────────────
+
+export type GradientDirection = 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+
+export interface GradientOverlayOptions {
+  /** Direction the gradient fades FROM (opaque end). Default: 'bottom' */
+  direction?: GradientDirection;
+  /** Gradient color. Default: '#000000' */
+  color?: string;
+  /** Opacity of the opaque end. 0–1. Default: 0.7 */
+  opacity?: number;
+  /** How much of the image the gradient covers. 0–1. Default: 0.5 */
+  coverage?: number;
+}
+
+// ─── ClipToShape ──────────────────────────────────────────────────────────────
+
+export type ClipShape = 'circle' | 'ellipse' | 'rounded-rect';
+
+export interface ClipToShapeOptions {
+  shape: ClipShape;
+  /** Border radius for 'rounded-rect'. Default: 32 */
+  borderRadius?: number;
+}
+
+// ─── DrawShape ────────────────────────────────────────────────────────────────
+
+export type ShapeType = 'rect' | 'circle' | 'ellipse' | 'line';
+
+export interface DrawShapeOptions {
+  /** Canvas width */
+  width: number;
+  /** Canvas height */
+  height: number;
+  /** Shape to draw */
+  shape: ShapeType;
+  /** Fill color. Default: 'transparent' */
+  fill?: string;
+  /** Fill opacity. 0–1. Default: 1 */
+  fillOpacity?: number;
+  /** Stroke color */
+  stroke?: string;
+  /** Stroke width. Default: 0 */
+  strokeWidth?: number;
+  /** Border radius (rect only). Default: 0 */
+  borderRadius?: number;
+  /** Circle/ellipse center X. Defaults to canvas center */
+  cx?: number;
+  /** Circle/ellipse center Y. Defaults to canvas center */
+  cy?: number;
+  /** Circle radius or ellipse rx */
+  r?: number;
+  /** Ellipse ry */
+  ry?: number;
+  /** Line start X */
+  x1?: number;
+  /** Line start Y */
+  y1?: number;
+  /** Line end X */
+  x2?: number;
+  /** Line end Y */
+  y2?: number;
+}
+
+// ─── DropShadow ───────────────────────────────────────────────────────────────
+
+export interface DropShadowOptions {
+  /** Shadow color. Default: 'rgba(0,0,0,0.5)' */
+  color?: string;
+  /** Shadow offset X. Default: 4 */
+  offsetX?: number;
+  /** Shadow offset Y. Default: 4 */
+  offsetY?: number;
+  /** Blur radius. Default: 8 */
+  blur?: number;
+  /** Expand canvas to fit shadow. Default: true */
+  expand?: boolean;
+}
+
 // ─── Pipeline ─────────────────────────────────────────────────────────────────
 
 export type PipelineOperation =
@@ -259,9 +353,14 @@ export type PipelineOperation =
   | ({ op: 'watermark' } & WatermarkOptions)
   | ({ op: 'convert' } & ConvertOptions)
   | ({ op: 'optimize' } & OptimizeOptions)
-  | ({ op: 'removeBg' } & RemoveBgOptions);
+  | ({ op: 'removeBg' } & RemoveBgOptions)
+  | ({ op: 'rotate' } & RotateOptions)
+  | ({ op: 'gradientOverlay' } & GradientOverlayOptions)
+  | ({ op: 'clipToShape' } & ClipToShapeOptions)
+  | ({ op: 'dropShadow' } & DropShadowOptions);
 
 export interface BatchOptions {
   concurrency?: number;
   onProgress?: (done: number, total: number) => void;
 }
+

package/tests/unit/clip-to-shape.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect, beforeAll } from 'vitest'
+import { readFileSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import sharp from 'sharp'
+import { clipToShape } from '../../src/ops/clip-to-shape.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const fixture = (name: string) => readFileSync(join(__dirname, '../fixtures', name))
+
+describe('clipToShape', () => {
+  let sampleJpeg: Buffer
+
+  beforeAll(() => {
+    sampleJpeg = fixture('sample.jpg')
+  })
+
+  it('clips to circle', async () => {
+    const result = await clipToShape(sampleJpeg, { shape: 'circle' })
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const meta = await sharp(result.data).metadata()
+    expect(meta.hasAlpha).toBe(true)
+  })
+
+  it('clips to rounded-rect with custom radius', async () => {
+    const result = await clipToShape(sampleJpeg, { shape: 'rounded-rect', borderRadius: 64 })
+    expect(result.ok).toBe(true)
+  })
+
+  it('clips to ellipse', async () => {
+    const result = await clipToShape(sampleJpeg, { shape: 'ellipse' })
+    expect(result.ok).toBe(true)
+  })
+})

package/tests/unit/draw-shape.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect } from 'vitest'
+import sharp from 'sharp'
+import { drawShape } from '../../src/ops/draw-shape.js'
+
+describe('drawShape', () => {
+  it('draws a filled rect', async () => {
+    const result = await drawShape({ width: 200, height: 100, shape: 'rect', fill: '#FF0000', borderRadius: 16 })
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const meta = await sharp(result.data).metadata()
+    expect(meta.width).toBe(200)
+    expect(meta.height).toBe(100)
+  })
+
+  it('draws a circle with stroke', async () => {
+    const result = await drawShape({ width: 100, height: 100, shape: 'circle', fill: '#00FF00', stroke: '#000000', strokeWidth: 3 })
+    expect(result.ok).toBe(true)
+  })
+
+  it('draws an ellipse', async () => {
+    const result = await drawShape({ width: 200, height: 100, shape: 'ellipse', fill: '#0000FF' })
+    expect(result.ok).toBe(true)
+  })
+
+  it('draws a line', async () => {
+    const result = await drawShape({ width: 200, height: 200, shape: 'line', stroke: '#FF0000', strokeWidth: 4, x1: 10, y1: 10, x2: 190, y2: 190 })
+    expect(result.ok).toBe(true)
+  })
+
+  it('returns error for unknown shape', async () => {
+    const result = await drawShape({ width: 100, height: 100, shape: 'hexagon' as any })
+    expect(result.ok).toBe(false)
+  })
+})

package/tests/unit/drop-shadow.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect, beforeAll } from 'vitest'
+import { readFileSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import sharp from 'sharp'
+import { dropShadow } from '../../src/ops/drop-shadow.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const fixture = (name: string) => readFileSync(join(__dirname, '../fixtures', name))
+
+describe('dropShadow', () => {
+  let logoPng: Buffer
+
+  beforeAll(() => {
+    logoPng = fixture('logo.png') // 100x100
+  })
+
+  it('adds drop shadow with expanded canvas', async () => {
+    const result = await dropShadow(logoPng, { blur: 8, offsetX: 4, offsetY: 4 })
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const meta = await sharp(result.data).metadata()
+    // Canvas should be expanded
+    expect(meta.width).toBeGreaterThan(100)
+    expect(meta.height).toBeGreaterThan(100)
+  })
+
+  it('adds shadow without expanding canvas', async () => {
+    const result = await dropShadow(logoPng, { expand: false, blur: 4 })
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const meta = await sharp(result.data).metadata()
+    expect(meta.width).toBe(100)
+    expect(meta.height).toBe(100)
+  })
+
+  it('uses default options', async () => {
+    const result = await dropShadow(logoPng)
+    expect(result.ok).toBe(true)
+  })
+})

package/tests/unit/gradient-overlay.test.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect, beforeAll } from 'vitest'
+import { readFileSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import { gradientOverlay } from '../../src/ops/gradient-overlay.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const fixture = (name: string) => readFileSync(join(__dirname, '../fixtures', name))
+
+describe('gradientOverlay', () => {
+  let sampleJpeg: Buffer
+
+  beforeAll(() => {
+    sampleJpeg = fixture('sample.jpg')
+  })
+
+  it('applies default bottom gradient', async () => {
+    const result = await gradientOverlay(sampleJpeg)
+    expect(result.ok).toBe(true)
+  })
+
+  it('applies gradient with custom direction and color', async () => {
+    const result = await gradientOverlay(sampleJpeg, {
+      direction: 'top-right', color: '#FF0000', opacity: 0.5, coverage: 0.8
+    })
+    expect(result.ok).toBe(true)
+  })
+})

package/tests/unit/rotate.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect, beforeAll } from 'vitest'
+import { readFileSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import sharp from 'sharp'
+import { rotate } from '../../src/ops/rotate.js'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const fixture = (name: string) => readFileSync(join(__dirname, '../fixtures', name))
+
+describe('rotate', () => {
+  let sampleJpeg: Buffer
+
+  beforeAll(() => {
+    sampleJpeg = fixture('sample.jpg')
+  })
+
+  it('rotates 90 degrees', async () => {
+    const result = await rotate(sampleJpeg, { angle: 90 })
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const meta = await sharp(result.data).metadata()
+    // 400x300 rotated 90° → 300x400
+    expect(meta.width).toBe(300)
+    expect(meta.height).toBe(400)
+  })
+
+  it('rotates 45 degrees with transparent bg', async () => {
+    const result = await rotate(sampleJpeg, { angle: 45 })
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const meta = await sharp(result.data).metadata()
+    // Canvas expands for 45° rotation
+    expect(meta.width).toBeGreaterThan(400)
+  })
+
+  it('returns same buffer for 0 degrees', async () => {
+    const result = await rotate(sampleJpeg, { angle: 0 })
+    expect(result.ok).toBe(true)
+  })
+})