# ImageBoss Elixir

Elixir client for generating [ImageBoss](https://imageboss.me) image URLs. ImageBoss resizes, compresses, and delivers your images through a global CDN via URL parameters.

[Documentation](https://imageboss.me/docs)

## Installation

Add `imageboss` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:imageboss, "~> 0.5"}
  ]
end
```

## Usage

Create a client with your ImageBoss **source** name (from your [dashboard](https://imageboss.me/dashboard/sources)):

```elixir
client = Imageboss.new(source: "mywebsite-images")
```

### Operations

**Cover** (crop to exact width and height):

```elixir
Imageboss.url(client, "/images/photo.jpg", :cover, width: 300, height: 300)
#=> "https://img.imageboss.me/mywebsite-images/cover/300x300/images/photo.jpg"
```

**Width** (fixed width, proportional height):

```elixir
Imageboss.url(client, "/images/photo.jpg", :width, width: 700)
```

**Height** (fixed height, proportional width):

```elixir
Imageboss.url(client, "/images/photo.jpg", :height, height: 400)
```

**CDN** (deliver through CDN without resizing):

```elixir
Imageboss.url(client, "/images/photo.jpg", :cdn)
```

### Cover options

- `:mode` — e.g. `"center"`, `"smart"`, `"face"`, `"northeast"`. See [Cover modes](https://imageboss.me/docs/operations/cover).
- `:options` — list of ImageBoss options as `"key:value"` strings (e.g. `["format:auto", "grayscale:true"]`).

### Extra options (all operations)

Pass `options: ["key:value", ...]` for filters and options (grayscale, format, download, etc.) as per [ImageBoss docs](https://imageboss.me/docs).

### Disabled mode (dev/test)

When you don't want to send images through ImageBoss (e.g. in tests or local dev), disable URL generation:

```elixir
client = Imageboss.new(source: "mywebsite", disabled: true)
Imageboss.url(client, "/images/photo.jpg", :width, width: 100)
#=> "/images/photo.jpg"
```

### Signed URLs

If your source has [signed URLs](https://imageboss.me/docs/security) enabled, pass your secret:

```elixir
client = Imageboss.new(source: "mywebsite", secret: "your-secret-token")
Imageboss.url(client, "/images/photo.jpg", :width, width: 100)
#=> "https://img.imageboss.me/mywebsite/width/100/images/photo.jpg?bossToken=..."
```

## Playground

Run the included Livebook notebook with the [Livebook](https://livebook.dev) escript (requires Elixir 1.18+).

**One-time install** (from this project directory so the right Elixir is used):

```bash
mix escript.install hex livebook
```

**Start the playground** (this is the `livebook` executable, not a Mix task—do not use `mix`).

asdf does not add Mix escripts to PATH; the binary lives in your Elixir install under `.mix/escripts/`. Run it with the full path:

- Bash/Zsh: `$(asdf where elixir)/.mix/escripts/livebook server imageboss_playground.livemd`
- Fish: `set -l lb (asdf where elixir)/.mix/escripts/livebook; $lb server imageboss_playground.livemd`

To have `livebook` on PATH, add the escripts directory to your shell config (after `asdf` is loaded):

- Bash/Zsh: `export PATH="$PATH:$(asdf where elixir)/.mix/escripts"`
- Fish: `fish_add_path (asdf where elixir)/.mix/escripts`

Then you can run `livebook server imageboss_playground.livemd` from anywhere.

Open the URL shown (e.g. http://localhost:8080). You can also open `imageboss_playground.livemd` in [Livebook Desktop](https://livebook.dev) or the VS Code Livebook extension.

## Testing

```bash
mix test
```

## Releasing a new version and publishing to Hex

Use the release script from the project root:

```bash
# Bump patch, run tests, and print next steps
mix run script/release.exs

# Bump minor or major
mix run script/release.exs minor
mix run script/release.exs major

# Set exact version
mix run script/release.exs 1.2.3

# Dry run (only bump version in mix.exs and run tests; no commit/tag/publish)
DRY_RUN=1 mix run script/release.exs
```

**Prerequisites:**

- Clean git working tree
- [Hex](https://hex.pm) account: `mix hex.user auth`

## License

MIT