# @suaveplan/caddy-imgproxy - Universal TypeScript port of the Caddy imgproxy URL rewriter — compact-grammar parser, aspect / pixel dimension resolver, gravity + operation translator, HMAC-SHA256 URL signer, full handler with Zod-validated config and OTel telemetry

Universal TypeScript port of the Caddy imgproxy URL rewriter.
Parses the compact `/u<op><gravity><dims><modifiers>/<path>.<format>`
grammar, resolves aspect-ratio + hint dimensions, translates gravity +
operations into imgproxy's URL DSL, signs the result with
HMAC-SHA256, and exposes a high-level `ImgproxyHandler` orchestrator
with injectable `Clock`, `LoggerLike`, and signing hash, plus
Zod-validated configuration and OTel telemetry.

<!-- begin:auto-docs -->
## Documentation tree

- [config](./src/config/config.md) — The `config` module exposes the Zod schema and the validating `parseConfig` function for the package's public `Imgproxy…
  - [config](./src/config/config.md) — The `config` module exposes the Zod schema and the validating `parseConfig` function for the package's public `Imgproxy…
- [dimensions](./src/dimensions/calculate-dimensions.md) — `calculateDimensions` resolves a `ParsedImgproxyUrl` plus the configured `defaultWidth` into a concrete `{ width, heigh…
  - [calculate-dimensions](./src/dimensions/calculate-dimensions.md) — `calculateDimensions` resolves a `ParsedImgproxyUrl` plus the configured `defaultWidth` into a concrete `{ width, heigh…
- [domain](./src/domain/extract-domain.md) — `extractDomain` translates an incoming HTTP `Host` header into the S3 sub-path segment that the URL builder interpolate…
  - [extract-domain](./src/domain/extract-domain.md) — `extractDomain` translates an incoming HTTP `Host` header into the S3 sub-path segment that the URL builder interpolate…
- [error-codes](./src/error-codes/error-codes.md) — The `error-codes` module is the canonical home of the package's stable error-code registry and the typed `CaddyImgproxy…
  - [error-codes](./src/error-codes/error-codes.md) — The `error-codes` module is the canonical home of the package's stable error-code registry and the typed `CaddyImgproxy…
- [gravity](./src/gravity/gravity.md) — The `gravity` module exposes the bidirectional translation between the compact one- or two-character grammar codes (`t`…
  - [gravity](./src/gravity/gravity.md) — The `gravity` module exposes the bidirectional translation between the compact one- or two-character grammar codes (`t`…
- [handler](./src/handler/handler.md) — `ImgproxyHandler` is the high-level orchestrator that wraps `parseImgproxyUrl`, `extractDomain`, and `buildImgproxyUrl`…
  - [handler](./src/handler/handler.md) — `ImgproxyHandler` is the high-level orchestrator that wraps `parseImgproxyUrl`, `extractDomain`, and `buildImgproxyUrl`…
- [operation](./src/operation/operation.md) — `operationToImgproxy` converts a resolved operation + concrete pixel dimensions + gravity into the imgproxy processing-…
  - [operation](./src/operation/operation.md) — `operationToImgproxy` converts a resolved operation + concrete pixel dimensions + gravity into the imgproxy processing-…
- [parse](./src/parse/parse-url.md) — `parseImgproxyUrl` parses the compact imgproxy URL grammar used by the Caddy module — `/[s|u]<op><gravity><dims><modifi…
  - [parse-url](./src/parse/parse-url.md) — `parseImgproxyUrl` parses the compact imgproxy URL grammar used by the Caddy module — `/[s|u]<op><gravity><dims><modifi…
- [signing](./src/signing/sign-path.md) — `signImgproxyPath` computes the HMAC-SHA256 URL signature that imgproxy requires when it is configured with a key + sal…
  - [sign-path](./src/signing/sign-path.md) — `signImgproxyPath` computes the HMAC-SHA256 URL signature that imgproxy requires when it is configured with a key + sal…
- [telemetry](./src/telemetry/telemetry.md) — The `telemetry` module owns the OTel instruments emitted by every public entry point in `@suaveplan/caddy-imgproxy`. It…
  - [telemetry](./src/telemetry/telemetry.md) — The `telemetry` module owns the OTel instruments emitted by every public entry point in `@suaveplan/caddy-imgproxy`. It…
- [types](./src/types/types.md) — The `types` module declares every cross-feature type that flows between the package's runtime modules: `ParsedImgproxyU…
  - [types](./src/types/types.md) — The `types` module declares every cross-feature type that flows between the package's runtime modules: `ParsedImgproxyU…
- [url-builder](./src/url-builder/url-builder.md) — `buildImgproxyUrl` composes the final imgproxy URL path from a parsed grammar representation. It is the orchestrator th…
  - [url-builder](./src/url-builder/url-builder.md) — `buildImgproxyUrl` composes the final imgproxy URL path from a parsed grammar representation. It is the orchestrator th…
<!-- end:auto-docs -->

## Install

```bash
bun add @suaveplan/caddy-imgproxy
```

## Quick start

```ts
import { ImgproxyHandler, parseConfig } from "@suaveplan/caddy-imgproxy";

const handler = new ImgproxyHandler({
    config: parseConfig({
        upstream: "imgproxy:8080",
        s3Bucket: "media",
        defaultWidth: 1200,
        key: "aa11bbcc",
        salt: "deadbeef",
    }),
});

const result = handler.rewrite({
    path: "/uvt9:16h1080/photos/hero.webp",
    host: "images.example.com",
});

if (result.rewritten) {
    forwardToImgproxy(result.targetPath);
} else if (result.reason === "passthrough") {
    forwardToImgproxy(originalPath);
}
```

## Modules

- [parse](./src/parse/parse-url.md) — compact-grammar parser.
- [dimensions](./src/dimensions/calculate-dimensions.md) — aspect /
  hint → pixel resolution.
- [gravity](./src/gravity/gravity.md) — grammar gravity → imgproxy
  compass tokens.
- [operation](./src/operation/operation.md) — operation +
  dimensions → imgproxy processing string.
- [signing](./src/signing/sign-path.md) — HMAC-SHA256 URL signing.
- [url-builder](./src/url-builder/url-builder.md) — composes the
  final imgproxy path.
- [domain](./src/domain/extract-domain.md) — Host header → S3
  sub-path.
- [handler](./src/handler/handler.md) — `ImgproxyHandler`
  orchestrator.
- [config](./src/config/config.md) — Zod-validated `ImgproxyConfig`.
- [error-codes](./src/error-codes/error-codes.md) —
  `CADDY_IMGPROXY_CODES` + `CaddyImgproxyError`.
- [telemetry](./src/telemetry/telemetry.md) — OTel counters +
  histogram.

## Tier & dependencies

Universal — no DOM or Node-only APIs at the package boundary.
`sideEffects: false`. Internal deps: `@suaveplan/crypto-hash`,
`@suaveplan/error`, `@suaveplan/types`. External deps:
`@opentelemetry/api`, `tslib`, `zod`.