npm package: @pixelfiddler/core
Description: Core utilities for PixelFiddler image transformation SDK
Author: PixelFiddler
Latest version: 1.0.2

# @pixelfiddler/core

Core utilities for building [PixelFiddler](https://pixel-fiddler.com) image transformation URLs.

## Installation

```bash
npm install @pixelfiddler/core
# or
pnpm add @pixelfiddler/core
# or
yarn add @pixelfiddler/core
```

## Usage

```typescript
import { buildTransformationUrl, buildTransformationQueryParams } from '@pixelfiddler/core';

// Build a complete transformation URL
const url = buildTransformationUrl({
  src: '/images/photo.jpg',
  baseUrl: 'https://cdn.example.com',
  transformations: {
    width: 800,
    height: 600,
    format: 'WEBP',
    quality: 85,
  }
});
// => 'https://cdn.example.com/images/photo.jpg?w=800&h=600&f=WEBP&q=85'

// Or just get the query string
const params = buildTransformationQueryParams({
  width: 400,
  blur: 5,
  grayscale: true,
});
// => 'w=400&bl=5&gs=true'
```

## API

### `buildTransformationUrl(config)`

Builds a complete transformation URL.

```typescript
buildTransformationUrl({
  src: '/photo.jpg',
  baseUrl: 'https://cdn.example.com',
  transformations: { width: 800, format: 'WEBP' },
  mode: 'short' // optional, default: 'short'
});
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `src` | `string` | Relative or absolute path to the image |
| `baseUrl` | `string` | Base URL endpoint from PixelFiddler Dashboard |
| `transformations` | `TransformationOptions` | Transformation options |
| `mode` | `'short' \| 'long'` | Parameter naming mode (default: `'short'`) |

### `buildTransformationQueryParams(options, mode?)`

Converts transformation options to a URL-encoded query string.

```typescript
buildTransformationQueryParams({ width: 800, format: 'WEBP' });
// => 'w=800&f=WEBP'

buildTransformationQueryParams({ width: 800 }, 'long');
// => 'width=800'
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `options` | `TransformationOptions` | Transformation options |
| `mode` | `'short' \| 'long'` | Parameter naming mode (default: `'short'`) |

### `createResponsiveAttributes(src, baseUrl?, options?)`

Generates responsive image attributes (src, srcSet, sizes) for optimal loading.

```typescript
import { createResponsiveAttributes } from '@pixelfiddler/core';

// Responsive image with sizes (uses `w` descriptors)
createResponsiveAttributes('/photo.jpg', 'https://cdn.example.com', {
  sizes: '(max-width: 768px) 100vw, 50vw',
  transformations: { format: 'WEBP' }
});
// => {
//   src: '...?w=3840&f=WEBP',
//   srcSet: '...?w=640&f=WEBP 640w, ...?w=1024&f=WEBP 1024w, ...',
//   sizes: '(max-width: 768px) 100vw, 50vw'
// }

// Fixed-width image (uses `x` descriptors for DPR)
createResponsiveAttributes('/photo.jpg', 'https://cdn.example.com', {
  width: 400
});
// => {
//   src: '...?w=384',
//   srcSet: '...?w=384 1x, ...?w=828 2x',
//   width: 400
// }
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `src` | `string` | Relative or absolute path to the image |
| `baseUrl` | `string` | Base URL endpoint from PixelFiddler Dashboard |
| `options.sizes` | `string` | Sizes attribute for responsive layouts |
| `options.width` | `number` | Fixed display width (generates DPR variants) |
| `options.deviceBreakpoints` | `number[]` | Custom device breakpoints |
| `options.imageBreakpoints` | `number[]` | Custom image breakpoints |
| `options.transformations` | `TransformationOptions` | Base transformations to apply |
| `options.maxDpr` | `number` | Maximum DPR to support (default: 2) |

## Transformation Options

### Resize

```typescript
{
  width: 800,           // Target width (px)
  height: 600,          // Target height (px)
  dpr: 2,               // Device pixel ratio (1-4)
  mode: 'FIT',          // 'FILL' | 'FIT' | 'PAD'
  background: '#ffffff' // Background color for PAD mode
}
```

### Format & Quality

```typescript
{
  format: 'WEBP',       // 'JPG' | 'PNG' | 'WEBP' | 'AVIF' | 'GIF'
  quality: 80,          // 1-100
  stripMetadata: true   // Remove EXIF data
}
```

### Effects

```typescript
{
  blur: 5,              // Gaussian blur (0-100)
  brightness: 10,       // Brightness adjustment (0-100)
  contrast: 20,         // Contrast adjustment (0-100)
  saturation: 30,       // Saturation adjustment (0-100)
  sharpen: 15,          // Sharpen intensity (0-100)
  noise: 5,             // Add noise (0-100)
  grayscale: true,      // Convert to grayscale
  sepia: true,          // Apply sepia effect
  rotate: 90            // Rotation (0 | 90 | 180 | 270)
}
```

### Border

```typescript
{
  border: {
    width: 2,           // Border width (px)
    color: '#000000',   // Border color
    radius: 8           // Corner radius (px, 1-2000)
  }
}
```

### Crop

```typescript
// Simple crop with auto focus
{
  crop: {
    type: 'SIMPLE',
    width: 400,
    height: 300,
    focus: {
      type: 'AUTO',
      strategy: 'SMART'     // 'CENTER' | 'SMART' | 'DETAIL'
    },
    afterResize: true
  }
}

// Simple crop with specified position
{
  crop: {
    type: 'SIMPLE',
    width: 400,
    height: 300,
    focus: {
      type: 'SPECIFIED',
      position: { x: 50, y: 50 }
    }
  }
}

// Object detection crop
{
  crop: {
    type: 'OBJECT',
    objectType: 'FACE',     // 'FACE' | 'UPPER_BODY'
    width: 400,
    height: 300
  }
}
```

### Text Overlay

```typescript
{
  text: {
    text: 'Hello World',
    color: '#ffffff',
    opacity: 80,            // 0-100
    size: 50,               // Size as percentage (1-100)
    font: 'Arial',
    fontSize: 24,           // Font size in pixels
    position: 'CENTER',     // Position constant
    background: '#000000',
    backgroundOpacity: 50
  }
}
```

### Watermark

```typescript
{
  watermark: {
    name: 'logo',           // Predefined watermark name
    opacity: 50,
    size: 25,               // Size as percentage
    width: 100,             // Or explicit dimensions
    height: 50,
    position: 'BOTTOM_RIGHT'
  }
}
```

### Position Values

For `text.position` and `watermark.position`:

```
'TOP_LEFT' | 'TOP' | 'TOP_RIGHT' |
'LEFT' | 'CENTER' | 'RIGHT' |
'BOTTOM_LEFT' | 'BOTTOM' | 'BOTTOM_RIGHT' |
'AUTO'
```

### Special Options

```typescript
{
  original: true,   // Return original image (no transformations)
  alias: 'thumb'    // Use predefined transformation alias
}
```

## Parameter Aliases

By default, short parameter names are used for smaller URLs:

| Option | Short | Long |
|--------|-------|------|
| width | `w` | `width` |
| height | `h` | `height` |
| format | `f` | `format` |
| quality | `q` | `quality` |
| blur | `bl` | `blur` |
| ... | ... | ... |

Use `mode: 'long'` for full parameter names:

```typescript
buildTransformationQueryParams({ width: 800 }, 'long');
// => 'width=800'
```

## TypeScript

Full TypeScript support with exported types:

```typescript
import type {
  // Main options
  TransformationOptions,
  PixelFiddlerConfig,
  UrlBuilderConfig,
  BuildTransformationConfig,

  // Resize
  ResizeOptions,
  ResizeMode,
  DevicePixelRatio,

  // Format
  FormatOptions,
  ImageFormat,

  // Effects
  EffectOptions,
  RotationAngle,

  // Border
  BorderOptions,
  HexColor,

  // Crop
  CropOptions,
  SimpleCropOptions,
  ObjectCropOptions,
  CropFocusOptions,
  CropType,
  CropFocus,
  CropFocusStrategy,
  CropObjectType,

  // Overlays
  TextOptions,
  WatermarkOptions,
  Position,
} from '@pixelfiddler/core';
```

## License

MIT