# `Image.Plug.Provider.ImageKit.URL`
[🔗](https://github.com/elixir-image/image_plug/blob/v0.1.0/lib/image/plug/provider/image_kit/url.ex#L1)

URL-shape recognition for the [ImageKit URL grammar](https://imagekit.io/docs/transformations).

ImageKit supports two URL forms; both are recognised:

* **Path-prefix** (default and most common):

      <host>/<endpoint>/tr:<transforms>/<source>

  where `<transforms>` is a comma-separated list of `key-value`
  pairs (e.g. `w-200,h-100,q-80`). Multi-stage chained transforms
  use `:` as the stage separator: `tr:w-200,h-100:rt-90`.

* **Query-string**:

      <host>/<endpoint>/<source>?tr=<transforms>

Both forms are equivalent on inbound. v0.1 flattens multi-stage
chained transforms by joining stages with `,` (the canonical IR
doesn't model chained transforms).

# `recognised`

```elixir
@type recognised() :: %{
  shape: :image_kit,
  options: String.t(),
  source: Image.Plug.Source.t()
}
```

The recognised URL shape.

# `parse`

```elixir
@spec parse(
  Plug.Conn.t(),
  keyword()
) :: {:ok, recognised()} | {:error, Image.Plug.Error.t()}
```

Parses the request path of a `Plug.Conn` into a recognised URL shape.

### Arguments

* `conn` is a `Plug.Conn` struct.

* `options` is a keyword list. The following keys are honoured:

### Options

* `:mount` — string path prefix the plug is mounted under.
  Stripped before processing. Defaults to `""`.

* `:endpoint` — additional path prefix to strip after `:mount`.
  ImageKit URLs commonly include a per-account endpoint segment
  (e.g. `/your_imagekit_id/`). Defaults to `""`.

### Returns

* `{:ok, recognised}` on a successful match.

* `{:error, %Image.Plug.Error{tag: :malformed_url}}` when the path
  doesn't sit under the configured mount/endpoint or has no
  source segment.

### Examples

    iex> conn = %Plug.Conn{
    ...>   path_info: ["tr:w-200,h-100", "sample.jpg"],
    ...>   request_path: "/tr:w-200,h-100/sample.jpg",
    ...>   query_string: ""
    ...> }
    iex> {:ok, parsed} = Image.Plug.Provider.ImageKit.URL.parse(conn, [])
    iex> parsed.options
    "w-200,h-100"
    iex> parsed.source.ref
    "/sample.jpg"

---

*Consult [api-reference.md](api-reference.md) for complete listing*