# image-client-api

> image-client-api

Latest version **1.4060.0** (published 2021-02-28) · UNLICENSED license · 0 weekly downloads

## Install

```sh
npm install image-client-api
pnpm add image-client-api
yarn add image-client-api
bun add image-client-api
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.4060.0 |
| Published | 2021-02-28 |
| First published | 2019-01-14 |
| Weekly downloads | 0 |
| License | UNLICENSED |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 1015.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | roir@wix.com |
| Maintainers | wix-ci, wix-ambassador, shahata, netanelgilad, wix-ci-publisher, wix-bi-publisher, cijoe, tyv |

## Links

- npm: https://www.npmjs.com/package/image-client-api
- Repository: https://github.com/wix-private/santa-core
- Homepage: https://github.com/wix-private/santa-core#readme
- Issues: https://github.com/wix-private/santa-core/issues
- npm.io page: https://npm.io/package/image-client-api

## Recent versions

- 1.4060.0 (latest) — 2021-02-28
- 0.0.0 (name-squat) — 2021-02-10
- 1.0.3 (old) — 2019-03-28
- 1.4059.0 — 2021-02-04
- 1.4058.0 — 2021-01-24
- 1.4057.0 — 2021-01-17
- 1.4056.0 — 2021-01-10
- 1.4055.0 — 2021-01-03
- 1.4054.0 — 2020-12-31
- 1.4053.0 — 2020-12-17
- 1.4052.0 — 2020-12-17
- 1.4051.0 — 2020-12-16
- 1.4050.0 — 2020-12-13
- 1.4049.0 — 2020-12-10
- 1.4048.0 — 2020-11-24
- … 1850 more at https://npm.io/package/image-client-api/versions

## README

# Image Client API
Standard library (~5K GZIP) for generating canonical URL's for consuming images at Wix, it generates the URL parameters 
for optimal image downloads.

## Features
* Maintaining pixel perfect images
* Ensuring minimum download latency, maximum performance and maximum quality
* Optimizing images for Retina displays 
* Fetching `.webp` images where applicable (browser support)
* Handling image sharpening when needed 
* Optimizing image upscaling (Wix machine learning) when needed

## Example

```js
import imageSDK from 'image-client-api';

const img = new Image();

img.src = imageSDK.getScaleToFillImageUrl('some-image.jpg', 1200, 800, 640, 480, { quality: 90 });
```

# Installation

You have 2 options:

## Install package

### In public (as open-source, dist only)

You can install the package via npm/yarn

```
> npm install -s image-client-api
```

or:

```
> yarn add image-client-api
```

### At Wix (with source)

You can install the package via npm/yarn

```
> npm install -s image-client-api --registry http://npm.dev.wixpress.com/
```

or:

```
> yarn add image-client-api --registry http://npm.dev.wixpress.com/
```

The default **UMD** modules can be found in `dist/`.

If you want **CommonJS** _only_ modules you can find them under `dist/cjs/`.

## Include script

Include the following tag in your document:

```html
<script src="https://static.parastorage.com/services/image-client-api/<version>/imageClientSDK.js"></script>
```

**Make sure to replace `<version>` with the version you need.**

If your server is provisioned by Chef you'll be provided with the correct URL.

## Usage

#### ES6 module

```js
import imageSDK from 'image-client-api';
```

#### CommonJS

```js
const imageSDK = require('image-client-api');
```

#### AMD

```js
define(['image-client-api'], function (imageSDK) { ... });
```

#### Gobal

```js
const imageSDK = window.imageClientSDK;
```

# API

| Method| Description |
| ------ | ----------- |
| [getScaleToFitImageURL()](#getScaleToFillImageUrl) | Scales the designated image to fit in the given target width and height while retaining the original proportions.|
| [getScaleToFillImageURL()](#getScaleToFillImageURL) | Scales the designated image with the exact given target width and height while retaining the original proportions. If the required proportions are different than the original, the image may be cropped to fill the provided width and height, so that only part of the original image might be visible. <br/><br/>The position pointing to the place from which to crop the image, if needed, is set by default to the vertical and horizontal center of the image or set to the focalPoint x,y values if presented. |
| [getCropImageURL()](#getCropImageURL) | Crops the designated image based on the supplied coordinates, starting at the x, y pixel coordinates, along with the width and height options. The image might be scaled according to the target dimensions. |

## Methods

### getScaleToFitImageUrl

```js
getScaleToFillImageUrl(
    relativeUrl,
    sourceWidth,
    sourceHeight,
    targetWidth,
    targetHeight,
    options
)
```

#### arguments

| name| description | type|
| ------ | ----------- | ------ |
| relativeUrl| the original image uri | string |
| sourceWidth | the original image width | number |
| sourceHeight | the original image height | number |
| targetWidth | target container width | number |
| targetHeight | target container height | number |
| options | additional image settings \[optional\] | object |

#### options

```js
{
   filters: {
      blur: 15
   },
   unsharpMask: {
      amount: 0.66,
      radius: 1.0,
      threshold: 0.01
   },
   name: 'hello kitty',
   quality: 80,
   upscaleMethod: 'classic',
   watermark: '3856-9876-76890-xzxz',
   isSEOBot: true
}
```

| key| valid values| default| type|
| --------- | -------- | ------ | ------ |
| filters.blur| 0-100 | - | number (%) |
| unsharpMask.amount| 0-10 | 0.66 | float |
| unsharpMask.radius| 0.1-500 | 1.0 | float |
| unsharpMask.amount| 0-255 | 0.01 | float |
| name| any string | '' | string |
| quality| 5-90 | 80 | number |
| upscaleMethod| 'auto', 'classic', 'super' | 'auto' | string |
| watermark| watermark manifest id | - | string |
| isSEOBot| true or false | false | boolean |

#### returns

returns image url \[string\]
<br/>

### getScaleToFillImageURL

```js
getScaleToFillImageUrl(
    relativeUrl,
    sourceWidth,
    sourceHeight,
    targetWidth,
    targetHeight,
    options
)
```

#### arguments

| name| description | type|
| ------ | ----------- | ------ |
| relativeUrl| the original image uri | string |
| sourceWidth | the original image width | number |
| sourceHeight | the original image height | number |
| targetWidth | target container width | number |
| targetHeight | target container height | number |
| options | additional image settings \[optional\] | object |

#### options

```js
{
   filters: {
      blur: 15
   },
   unsharpMask: {
      amount: 0.66,
      radius: 1.0,
      threshold: 0.01
   },
   focalPoint: {
      x: 50,
      y: 50
   },
   name: 'hello kitty',
   quality: 80, 
   upscaleMethod: 'classic'
   watermark: '3856-9876-76890-xzxz',
   isSEOBot: true
}
```

| key| valid values| default| type|
| --------- | ------------ | ------ | ------ |
| filters.blur| 0-100 | - | number (%) |
| unsharpMask.amount| 0-10 | 0.66 | float |
| unsharpMask.radius| 0.1-500 | 1.0 | float |
| unsharpMask.amount| 0-255 | 0.01 | float |
| focalPoint.x | 0-100 | - | number (%) |
| focalPoint.y | 0-100 | - | number (%) |
| name| any string | '' | string |
| quality| 5-90 | 80 | number |
| upscaleMethod| 'auto', 'classic', 'super' | 'auto' | string |
| watermark| watermark manifest id | - | string |
| isSEOBot| true or false | false | boolean |

#### returns

returns image url \[string\]
<br/>

### getCropImageURL

```js
getCropImageUrl(
    relativeUrl,
    sourceWidth,
    sourceHeight,
    cropX,
    cropY,
    cropWidth,
    cropHeight,
    targetWidth,
    targetHeight,
    options
)
```

#### arguments

| name | description | type |
| ------ | ----------- | ------ |
| relativeUrl| the original image uri | string |
| sourceWidth | the original image width | number |
| sourceHeight | the original image height | number |
| cropX | the X pixel coordinate to start cropping from | number |
| cropY | the Y pixel coordinate to start cropping from | number |
| cropWidth | the width constraint | number |
| cropHeight | the height constraint | number |
| targetWidth | target container width | number |
| targetHeight | target container height | number |
| options | additional image settings \[optional\] | object |

#### options

```js
{
   filters: {
      blur: 15
   },
   unsharpMask: {
      amount: 0.66,
      radius: 1.0,
      threshold: 0.01
   },
   focalPoint: {
      x: 50,
      y: 50
   },
   name: 'hello kitty',
   quality: 80, 
   upscaleMethod: 'classic',
   watermark: '3856-9876-76890-xzxz',
   isSEBot: true
}
```

| key| valid values| default| type|
| --------- | ------------ | ------ | ------ |
| filters.blur| 0-100 | - | number (%) |
| unsharpMask.amount| 0-10 | 0.66 | float |
| unsharpMask.radius| 0.1-500 | 1.0 | float|
| unsharpMask.amount| 0-255 | 0.01 | float|
| name| any string | '' | string |
| quality| 5-90 | 80 | number|
| upscaleMethod| 'auto', 'classic', 'super' | 'auto' | string |
| watermark| watermark manifest id | - | string |
| isSEOBot| true or false | false | boolean |

#### returns

returns image url \[string\]
<br/>

---
_Source: https://npm.io/package/image-client-api · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._