npm package: @flyimg/flyimg.js
Description: Interact with a Flyimg endpoint: build URLs with the needed transformations options.
Latest version: 1.1.0

# @flyimg/flyimg.js

<p align="center">
  <a href="https://flyimg.io" target="_blank">
    <img alt="Flyimg" src="https://raw.githubusercontent.com/flyimg/graphic-assets/main/logo/raster/flyimg-logo-rgb.png" width="300">
  </a>
  <br />
    <a href="https://flyimg.io/"><strong>Official website »</strong></a>
    <br />
    <a href="https://github.com/flyimg/flyimg">GitHub</a>
    ·
    <a href="https://github.com/flyimg/flyimg/issues">Bugs Report</a>
</p>

A Node.js client for Flyimg – easily build transformation URLs and fetch processed images directly from your Flyimg instance.

## Install

```bash
npm i @flyimg/flyimg.js
```

## Usage

```ts
import { flyimg, flyimgUpload } from '@flyimg/flyimg.js';

// log upload and download progress
const onDownloadProgress = console.log;
const onUploadProgress = console.log;

flyimg({
  instanceUrl: process.env.INSTANCE_URL!,
  inputImage: './input.png', // local path OR http(s) URL
  onDownloadProgress,
  onUploadProgress,
  options: {
    quality: 80,
    output: 'png',
  },
}).then(({ outputImagePath, cleanup }) => {
  console.log(`image transformed and saved under path=${outputImagePath}`);
  // await cleanup();
});
```

- For local files, the client POSTs to `${instanceUrl}/upload` and expects `{ url }`.
- The transformed image is streamed to a temp file. Call `cleanup()` to remove it.


## API

- `flyimg({ instanceUrl, inputImage, options?, onDownloadProgress?, onUploadProgress? })`
  - Returns: `{ outputImagePath, cleanup }`

- `flyimgUpload({ instanceUrl, input, options?, contentType?, onDownloadProgress? })`
  - `input` can be one of:
    - raw binary: `Buffer`, `Uint8Array`, or `ReadableStream`
    - JSON bodies: `{ base64: string }` or `{ dataUri: string }`
  - When using raw binary, set `contentType` (e.g. `image/png`); defaults to `application/octet-stream`.
  - Returns: `{ outputImagePath, cleanup }`

## Options reference

See the upstream Flyimg documentation for full details and semantics: [`url-options.md`](https://github.com/flyimg/flyimg/blob/main/docs/url-options.md).

Below are the option names accepted by this package. They are converted into the proper Flyimg URL query parameters. Pass them under `options` when calling `flyimg`.

| Long name | Short key | Description |
| --- | --- | --- |
| `quality` | `q` | Output quality (integer, e.g. 80). |
| `output` | `o` | Output format, e.g. `jpg`, `png`, `webp`, `avif`, or `auto`. |
| `unsharp` | `unsh` | Apply unsharp mask (e.g. radius×sigma+amount). |
| `sharpen` | `sh` | Sharpen amount/preset. |
| `blur` | `blr` | Gaussian blur radius/sigma. |
| `face-crop` | `fc` | Enable face crop (boolean or mode). |
| `face-crop-position` | `fcp` | Face crop position or index. |
| `face-blur` | `fb` | Blur detected faces (intensity). |
| `width` | `w` | Target width in pixels. |
| `height` | `h` | Target height in pixels. |
| `crop` | `c` | Crop geometry or mode (e.g. `WxH+X+Y` or keywords). |
| `background` | `bg` | Background color (e.g. `white`, `#RRGGBB`). |
| `strip` | `st` | Strip metadata (1 to strip, 0 to keep). |
| `auto-orient` | `ao` | Auto rotate based on EXIF (0/1). |
| `resize` | `rz` | Resize mode (fit, fill, etc.). |
| `gravity` | `g` | Gravity for crop/extent (e.g. `Center`, `NorthWest`). |
| `filter` | `f` | Resampling filter (e.g. `Lanczos`). |
| `rotate` | `r` | Rotate degrees (e.g. 90). |
| `text` | `t` | Overlay text string. |
| `text-color` | `tc` | Text color (e.g. `white`, `#RRGGBB`). |
| `text-size` | `ts` | Text font size. |
| `text-bg` | `tbg` | Text background color. |
| `scale` | `sc` | Scale factor (e.g. 2 for 2x). |
| `sampling-factor` | `sf` | Chroma subsampling (e.g. `1x1`, `2x2`). |
| `refresh` | `rf` | Force refresh/bypass cache (boolean). |
| `smart-crop` | `smc` | Enable smart cropping (boolean). |
| `extent` | `ett` | Extent canvas size (e.g. `WxH`). |
| `preserve-aspect-ratio` | `par` | Keep aspect ratio (0/1). |
| `preserve-natural-size` | `pns` | Avoid upscaling beyond natural size (0/1). |
| `webp-lossless` | `webpl` | WebP lossless mode (0/1). |
| `webp-method` | `webpm` | WebP encoding method (0–6). |
| `gif-frame` | `gf` | Extract specific GIF frame (index). |
| `extract` | `e` | Extract region (geometry). |
| `extract-top-x` | `p1x` | Extract top-left X. |
| `extract-top-y` | `p1y` | Extract top-left Y. |
| `extract-bottom-x` | `p2x` | Extract bottom-right X. |
| `extract-bottom-y` | `p2y` | Extract bottom-right Y. |
| `pdf-page-number` | `pdfp` | PDF page to render (1-based). |
| `density` | `dnst` | DPI/density for vector/PDF rasterization. |
| `time` | `tm` | Video time offset (e.g. `00:00:01`). |
| `colorspace` | `clsp` | Colorspace (e.g. `sRGB`). |
| `monochrome` | `mnchr` | Convert to monochrome (boolean or params). |

### Examples

- Resize and format:
```ts
await flyimg({
  instanceUrl,
  inputImage: 'https://example.com/a.jpg',
  options: { width: 800, height: 600, output: 'webp', quality: 82 },
});
```

- Smart crop to square and set background:
```ts
await flyimg({
  instanceUrl,
  inputImage: './local.png',
  options: { smart-crop: true, extent: '512x512', background: '#000000' },
});
```

- Overlay text:
```ts
await flyimg({
  instanceUrl,
  inputImage: 'https://example.com/hero.jpg',
  options: { text: 'Hello', 'text-color': 'white', 'text-size': 32 },
});
```

- Upload raw binary directly (POST) with options inline:
```ts
import fs from 'node:fs';

const buffer = await fs.promises.readFile('./local.png');
const { outputImagePath } = await flyimgUpload({
  instanceUrl,
  input: buffer, // or a Readable stream
  contentType: 'image/png',
  options: { width: 800, height: 600, output: 'webp', quality: 82 },
});
```

- Upload Base64 JSON:
```ts
const base64 = (await fs.promises.readFile('./local.jpg')).toString('base64');
const { outputImagePath } = await flyimgUpload({
  instanceUrl,
  input: { base64 },
  options: { output: 'avif', quality: 60 },
});
```

- Upload Data URI JSON:
```ts
const dataUri = 'data:image/png;base64,' + (await fs.promises.readFile('./img.png')).toString('base64');
const { outputImagePath } = await flyimgUpload({
  instanceUrl,
  input: { dataUri },
  options: { webp-lossless: 1 },
});
```

### Test Example folder

```
npx http-server example -c-1 -p 5174
```