@zio.dev/zio-blocks 0.0.33 → 0.0.51

package/reference/endpoint/auth-type.md

@@ -0,0 +1,146 @@
+---
+id: auth-type
+title: "AuthType"
+---
+
+`AuthType` is a sealed trait that describes an HTTP authentication scheme as a first-class type parameter on `Endpoint`. Each `AuthType` variant carries an associated type `ClientRequirement` — the type of credential the client must provide — and a codec that extracts it from the request. Its definition is:
+
+```scala
+sealed trait AuthType {
+  type ClientRequirement
+  def codec: HttpCodec[CodecKind.Request, ClientRequirement]
+  def unauthorizedStatus: Status
+}
+```
+
+## Motivation
+
+Authentication requirements are often encoded informally — a comment in the handler, a middleware convention, or a bare string header check. `AuthType` makes the auth requirement part of the endpoint's static type. A bearer-secured endpoint has type `Endpoint[..., AuthType.Bearer]`, which means:
+
+- The `auth.codec` field is typed as `HttpCodec[CodecKind.Request, zio.http.Header.Authorization.Bearer]`, not `HttpCodec[..., String]`.
+- Interpreters (server, client, OpenAPI) can inspect the auth type without stringly-typed reflection.
+- Composing auth types with `|` produces a union that the compiler verifies is discriminated.
+
+## Built-in Variants
+
+Each built-in variant maps to a specific HTTP authorization scheme. Use the one that matches your API's authentication model.
+
+### `AuthType.None`
+
+The default auth type — no authentication required. Its `ClientRequirement` is `Unit` and its codec is `HttpCodec.Empty`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val publicEndpoint = Endpoint(Method.GET / "health")
+```
+
+### `AuthType.Basic`
+
+HTTP Basic authentication. The `ClientRequirement` is `zio.http.Header.Authorization.Basic`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val basicEndpoint = Endpoint(Method.GET / "admin")
+  .auth(AuthType.Basic)
+
+val codec = basicEndpoint.auth.codec
+```
+
+### `AuthType.Bearer`
+
+Bearer token authentication (OAuth 2.0 / JWT). The `ClientRequirement` is `zio.http.Header.Authorization.Bearer`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val bearerEndpoint = Endpoint(Method.GET / "me")
+  .auth(AuthType.Bearer)
+```
+
+### `AuthType.Digest`
+
+HTTP Digest authentication. The `ClientRequirement` is `zio.http.Header.Authorization.Digest`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val digestEndpoint = Endpoint(Method.GET / "secure")
+  .auth(AuthType.Digest)
+```
+
+### `AuthType.Custom`
+
+For authentication schemes not covered by the built-in variants, `Custom` wraps any `HttpCodec[CodecKind.Request, ClientReq]`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.schema.Schema
+import zio.http.Method
+
+final case class ApiKey(value: String)
+
+val apiKeyCodec = HttpCodec.requestHeader("X-Api-Key", Schema.string.transform[ApiKey](ApiKey(_), _.value))
+val apiKeyAuth  = AuthType.Custom(apiKeyCodec)
+val keyEndpoint = Endpoint(Method.GET / "data").auth(apiKeyAuth)
+```
+
+## Composition
+
+`AuthType` values compose in two ways: `|` builds an OR alternative that accepts either scheme, and `Scoped` attaches scope requirements to an existing auth type.
+
+### `AuthType#|` — OR composition
+
+Two `AuthType` values can be combined with `|` to accept either scheme. The result is an `AuthType.Or` whose `ClientRequirement` is the union of both:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val flexEndpoint = Endpoint(Method.GET / "resource")
+  .auth(AuthType.Basic | AuthType.Bearer)
+```
+
+The `|` operator automatically computes the combined `ClientRequirement` type as a union of both requirements. The codec of the resulting `Or` is a `HttpCodec.Fallback` — it tries the left scheme first and falls back to the right.
+
+### `AuthType.Scoped`
+
+To attach OAuth scope requirements to a bearer auth, wrap it in `AuthType.Scoped`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val scopedEndpoint = Endpoint(Method.GET / "admin")
+  .auth(AuthType.Scoped(AuthType.Bearer, List("admin:read", "admin:write")))
+```
+
+`Scoped` does not change the codec — it carries the scopes as metadata for interpreters that perform scope-level authorization checks.
+
+## Unauthorized Status
+
+By default, `AuthType` returns `Status.NotFound` when the client does not meet the auth requirement (to avoid leaking endpoint existence). To change this, use `Endpoint#unauthorizedStatus` or call `AuthType#withUnauthorizedStatus` directly:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.{Method, Status}
+
+val endpoint = Endpoint(Method.GET / "me")
+  .auth(AuthType.Bearer)
+  .unauthorizedStatus(Status.Unauthorized)
+```
+
+`Or` composition preserves `AuthType#unauthorizedStatus` — it uses the left auth type's status.

package/reference/endpoint/endpoint.md

@@ -0,0 +1,297 @@
+---
+id: endpoint
+title: "Endpoint"
+---
+
+`Endpoint[PathInput, Input, Err, Output, Auth]` is the top-level descriptor for an HTTP endpoint. It holds a typed route, three independent codec channels (request input, error output, success output), an authentication type, and documentation metadata. `Endpoint` is pure data — it carries no server or client logic and imposes no effect type. Its full shape is:
+
+```scala
+final case class Endpoint[PathInput, Input, Err, Output, Auth <: AuthType](
+  route: RoutePattern[PathInput],
+  input: HttpCodec[CodecKind.Request, Input],
+  error: HttpCodec[CodecKind.Response, Err],
+  output: HttpCodec[CodecKind.Response, Output],
+  auth: Auth,
+  doc: Doc
+)
+```
+
+## Motivation
+
+An endpoint descriptor separates the **shape** of an HTTP surface from its **execution**. A single `Endpoint` value can be interpreted by a server to generate routes, by a client generator to produce typed API calls, or by an OpenAPI renderer to produce specification documents. This means the endpoint definition is the single source of truth — change it once and every interpreter updates.
+
+The five type parameters track everything the compiler needs to enforce consistency across the whole stack:
+
+| Parameter   | Meaning                                                    |
+|-------------|------------------------------------------------------------|
+| `PathInput` | Type of values extracted from path segments                |
+| `Input`     | Aggregate type of all request inputs (query, header, body) |
+| `Err`       | Aggregate type of all error response shapes                |
+| `Output`    | Aggregate type of all success response shapes              |
+| `Auth`      | Authentication scheme, carries the client requirement      |
+
+## Construction
+
+We create an `Endpoint` from a `RoutePattern` using `Endpoint.apply`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val ep = Endpoint(Method.GET / "users" / PathCodec.int("id"))
+```
+
+The route can also be built from a separate `RoutePattern` value:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val route = Method.POST / "orders" / PathCodec.uuid("orderId")
+val ep    = Endpoint(route)
+```
+
+The initial `Endpoint` starts with `Unit` for all three codec channels and `AuthType.None` for auth, so further builder calls always widen the types additively.
+
+## Request Input Builders
+
+Every `Endpoint#in`, `Endpoint#query`, and `Endpoint#header` call adds another input component to the endpoint, widening the `Input` type parameter.
+
+### Body input
+
+To add a request body typed by a `Schema`, use `Endpoint#in`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.schema.Schema
+import zio.http.Method
+
+val ep = Endpoint(Method.POST / "users")
+  .in(Schema.string)
+```
+
+To specify the content type explicitly, pass a `MediaType` as well:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.mediatype.MediaTypes
+import zio.blocks.schema.Schema
+import zio.http.Method
+
+val ep = Endpoint(Method.POST / "users")
+  .in(MediaTypes.application.`json`, Schema.string)
+```
+
+To add a raw `HttpCodec.Body` node directly, use `Endpoint#in`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.schema.Schema
+import zio.http.Method
+
+val ep = Endpoint(Method.POST / "users")
+  .in(HttpCodec.requestBody(Schema.string))
+```
+
+### Query parameters
+
+To add a query parameter by name and schema, use `Endpoint#query`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.schema.Schema
+import zio.http.Method
+
+val ep = Endpoint(Method.GET / "users")
+  .query("page", Schema.int)
+  .query("limit", Schema.int)
+```
+
+To add a pre-built `HttpCodec.Query` node, use `Endpoint#query`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.schema.Schema
+import zio.http.Method
+
+val pageCodec = HttpCodec.query("page", Schema.int)
+val ep        = Endpoint(Method.GET / "users").query(pageCodec)
+```
+
+### Request headers
+
+To add a request header by name and schema, use `Endpoint#header`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.schema.Schema
+import zio.http.Method
+
+val ep = Endpoint(Method.GET / "users")
+  .header("X-Trace-Id", Schema.string)
+```
+
+To add a pre-built `HttpCodec.Header` node, use `Endpoint#header`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.schema.Schema
+import zio.http.Method
+
+val traceCodec = HttpCodec.requestHeader("X-Trace-Id", Schema.string)
+val ep         = Endpoint(Method.GET / "users").header(traceCodec)
+```
+
+## Success Output Builders
+
+Every `Endpoint#out` and `Endpoint#outHeader` call adds a success response alternative or header component, widening `Output`.
+
+### Response body
+
+To add a 200 OK response body, use `Endpoint#out`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.schema.Schema
+import zio.http.Method
+
+val ep = Endpoint(Method.GET / "users")
+  .out(Schema.string)
+```
+
+To specify a non-200 status code, use `Endpoint#out` with a `Status`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.schema.Schema
+import zio.http.{Method, Status}
+
+val ep = Endpoint(Method.POST / "users")
+  .out(Status.Created, Schema.int)
+```
+
+To add content-type negotiation, pass a `MediaType`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.mediatype.MediaTypes
+import zio.blocks.schema.Schema
+import zio.http.{Method, Status}
+
+val ep = Endpoint(Method.GET / "users")
+  .out(MediaTypes.application.`json`, Schema.string)
+  .out(Status.Created, MediaTypes.text.`plain`, Schema.int)
+```
+
+Multiple `Endpoint#out` calls produce alternatives. The output type widens from `Unit` to the first schema type, then to a nested `Either` for each additional alternative.
+
+### Response headers
+
+To add a typed response header, use `Endpoint#outHeader`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.schema.Schema
+import zio.http.Method
+
+val ep = Endpoint(Method.GET / "users")
+  .out(Schema.string)
+  .outHeader("X-Total-Count", Schema.int)
+```
+
+## Error Output Builders
+
+Error channels work like success channels but populate the `Err` type parameter. Two variants exist: `Endpoint#outError` (cross-version) and `Endpoint#orOutError` (Scala 3 unions).
+
+### `Endpoint#outError` — cross-version additive errors
+
+To add an error response with a status code and body schema, use `Endpoint#outError`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.schema.Schema
+import zio.http.{Method, Status}
+
+val ep = Endpoint(Method.GET / "users")
+  .out(Schema.string)
+  .outError(Status.NotFound, Schema.string)
+  .outError(Status.BadRequest, Schema.string)
+```
+
+Each `Endpoint#outError` call widens `Err` by one nested `Either` layer.
+
+### `Endpoint#orOutError` — Scala 3 union errors
+
+On Scala 3, `Endpoint#orOutError` accumulates error types as a native union type instead of nested `Either`s. The first call replaces the initial `Unit` error outright; subsequent calls build a `Fallback` codec backed by `Unions` derivation:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.blocks.schema.Schema
+import zio.http.{Method, Status}
+
+val ep = Endpoint(Method.GET / "users")
+  .orOutError(Status.NotFound, Schema.string)
+  .orOutError(Status.Conflict, Schema.int)
+
+val typed: Endpoint[Unit, Unit, String | Int, Unit, AuthType.None.type] = ep
+```
+
+The compiler rejects overlapping union members — two `Endpoint#orOutError` calls both using `Schema.string` produce a compile error because `String | String` is not a valid discriminated union.
+
+## Authentication
+
+To attach an authentication scheme, use `Endpoint#auth`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val secured = Endpoint(Method.GET / "me")
+  .auth(AuthType.Bearer)
+```
+
+The `Auth` type parameter carries the `ClientRequirement` associated type, so a bearer-secured endpoint exposes `auth.codec` typed as `HttpCodec[CodecKind.Request, zio.http.Header.Authorization.Bearer]`. See [AuthType](./auth-type.md) for all variants.
+
+To override the HTTP status the server sends when the client does not meet the auth requirement, use `Endpoint#unauthorizedStatus`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.{Method, Status}
+
+val secured = Endpoint(Method.GET / "me")
+  .auth(AuthType.Bearer)
+  .unauthorizedStatus(Status.Unauthorized)
+```
+
+## Documentation
+
+To attach a `Doc` value to the endpoint as a whole, use `Endpoint#doc`:
+
+```scala
+import zio.blocks.docs.Doc
+import zio.blocks.endpoint._
+import zio.blocks.endpoint.RoutePattern._
+import zio.http.Method
+
+val ep = Endpoint(Method.GET / "users")
+  .doc(Doc.empty)
+```
+
+Documentation attached here flows through to OpenAPI generation and any other documentation interpreters.

package/reference/endpoint/http-codec.md

@@ -0,0 +1,249 @@
+---
+id: http-codec
+title: "HttpCodec"
+---
+
+`HttpCodec[K, A]` is a composable, typed descriptor for HTTP request and response parts. The phantom type parameter `K` (either `CodecKind.Request` or `CodecKind.Response`) tracks which direction the codec belongs to, so the compiler prevents mixing request-side codecs (query, request header, request body) with response-side codecs (status, response header, response body). The trait signature is:
+
+```scala
+sealed trait HttpCodec[+K <: CodecKind, A]
+```
+
+## Motivation
+
+HTTP surfaces have two directions — request and response — and each direction has several distinct parts. Without static direction tracking, it is easy to accidentally pass a response status codec where a request header codec is expected, or combine a query parameter with a response body.
+
+`HttpCodec` makes that class of mistake a compile error. The phantom type `K` carries direction at the type level, so `HttpCodec[CodecKind.Request, A]` and `HttpCodec[CodecKind.Response, A]` are incompatible types. All combinators (`++`, `|`) preserve this constraint: combining two request codecs yields a request codec, and combining request with response is a type error.
+
+## `CodecKind`
+
+`CodecKind` is a phantom type hierarchy with two sealed subtypes:
+
+```scala
+sealed trait CodecKind
+
+object CodecKind {
+  sealed trait Request  extends CodecKind  // query, request header, request body
+  sealed trait Response extends CodecKind  // status, response header, response body
+}
+```
+
+These are never instantiated — they exist only to parameterize `HttpCodec[K, A]` at the type level.
+
+## Structure
+
+`HttpCodec` is an ADT with seven node types:
+
+| Node          | Kind      | Carries                                              |
+| ------------- | --------- | ---------------------------------------------------- |
+| `Empty`       | both      | No data — neutral element for `++`                  |
+| `Combine`     | both      | Two codecs composed sequentially with `++`           |
+| `Fallback`    | both      | Two codecs composed as alternatives with `&#124;`    |
+| `Query`       | `Request` | Named query parameter with `Schema[A]`               |
+| `Header`      | both      | Named HTTP header with `Schema[A]` (request or response) |
+| `Body`        | both      | Request or response body with `Schema[A]`            |
+| `StatusCodec` | `Response`| HTTP status code                                     |
+
+## Construction
+
+Smart constructors on the `HttpCodec` companion build each atom type. Choose the constructor that matches the HTTP part you are describing.
+
+### Query parameters
+
+To describe a named query parameter, use `HttpCodec.query`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.schema.Schema
+
+val limitCodec: HttpCodec.Query[Int] = HttpCodec.query("limit", Schema.int)
+```
+
+Optional fields on `Query` include `default`, `doc`, `examples`, and `deprecated`. To create a query codec with a default value:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.schema.Schema
+
+val pageCodec = HttpCodec.query("page", Schema.int, default = Some(1))
+```
+
+### Request headers
+
+To describe a request header by name and schema, use `HttpCodec.requestHeader`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.schema.Schema
+
+val traceHeader: HttpCodec.Header[CodecKind.Request, String] =
+  HttpCodec.requestHeader("X-Trace-Id", Schema.string)
+```
+
+To use a zio-http typed header instance (which provides its own name and parse/render logic), pass the typed header directly:
+
+```scala
+import zio.blocks.endpoint._
+import zio.http.Header
+
+val authHeader: HttpCodec.Header[CodecKind.Request, Header.Authorization] =
+  HttpCodec.requestHeader(Header.Authorization)
+```
+
+### Response headers
+
+To describe a response header, use `HttpCodec.responseHeader`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.schema.Schema
+
+val totalCount: HttpCodec.Header[CodecKind.Response, Int] =
+  HttpCodec.responseHeader("X-Total-Count", Schema.int)
+```
+
+### Request body
+
+To describe a request body, use `HttpCodec.requestBody`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.schema.Schema
+
+val body: HttpCodec[CodecKind.Request, String] =
+  HttpCodec.requestBody(Schema.string)
+```
+
+To restrict the accepted content types, pass a `Chunk[MediaType]`:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.endpoint._
+import zio.blocks.mediatype.MediaTypes
+import zio.blocks.schema.Schema
+
+val jsonBody: HttpCodec[CodecKind.Request, String] =
+  HttpCodec.requestBody(Schema.string, mediaTypes = Chunk.single(MediaTypes.application.`json`))
+```
+
+### Response body
+
+To describe a response body, use `HttpCodec.responseBody`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.schema.Schema
+
+val body: HttpCodec[CodecKind.Response, String] =
+  HttpCodec.responseBody(Schema.string)
+```
+
+### Status codes
+
+To describe a required HTTP status code, use `HttpCodec.status`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.http.Status
+
+val created: HttpCodec[CodecKind.Response, Unit] = HttpCodec.status(Status.Created)
+```
+
+Predefined status constants are available directly on `HttpCodec`:
+
+```scala
+import zio.blocks.endpoint._
+
+val ok           = HttpCodec.Ok
+val created      = HttpCodec.Created
+val notFound     = HttpCodec.NotFound
+val badRequest   = HttpCodec.BadRequest
+val unauthorized = HttpCodec.Unauthorized
+```
+
+For any other status code, use `HttpCodec.CustomStatus(code)`.
+
+## Composition
+
+Two operators combine `HttpCodec` values: `++` sequences parts within the same direction, while `|` creates alternatives for content negotiation or multi-status responses.
+
+### Sequential composition with `++`
+
+`++` combines two codecs of the same direction into a single codec whose type is the product of both. The result type is automatically flattened, eliminating `Unit` components and nested tuples:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.schema.Schema
+
+val queryAndHeader: HttpCodec[CodecKind.Request, (String, Int)] =
+  HttpCodec.query("name", Schema.string) ++ HttpCodec.query("age", Schema.int)
+```
+
+The compiler rejects mixing directions — combining a request codec with a response codec is a type error:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.schema.Schema
+import zio.http.Status
+
+// This would be a compile error:
+// HttpCodec.query("name", Schema.string) ++ HttpCodec.status(Status.Ok)
+```
+
+### Alternative composition with `|`
+
+`|` combines two codecs as alternatives. The result type is automatically computed as a nested `Either`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.blocks.schema.Schema
+import zio.http.Status
+
+val okOrCreated =
+  (HttpCodec.responseBody(Schema.string) ++ HttpCodec.Ok) |
+  (HttpCodec.responseBody(Schema.int) ++ HttpCodec.Created)
+```
+
+## Authentication Codecs
+
+Pre-built request codecs for common authorization header schemes are available on `HttpCodec`:
+
+```scala
+import zio.blocks.endpoint._
+import zio.http.Header
+
+val basic: HttpCodec[CodecKind.Request, Header.Authorization.Basic]   = HttpCodec.basicAuth
+val bearer: HttpCodec[CodecKind.Request, Header.Authorization.Bearer] = HttpCodec.bearerAuth
+val digest: HttpCodec[CodecKind.Request, Header.Authorization.Digest] = HttpCodec.digestAuth
+val proxy: HttpCodec[CodecKind.Request, Header.ProxyAuthorization]    = HttpCodec.proxyAuthorization
+```
+
+These codecs use `Schema.transform` internally to parse the raw `Authorization` header string into the typed zio-http auth model, surfacing a `SchemaError` if the scheme does not match.
+
+## Metadata Fields
+
+Every atom node (`Query`, `Header`, `Body`, `StatusCodec`) carries optional metadata that documentation renderers and OpenAPI generators consume:
+
+| Field        | Type              | Purpose                                        |
+| ------------ | ----------------- | ---------------------------------------------- |
+| `doc`        | `Doc`             | Free-text description for OpenAPI output       |
+| `examples`   | `Chunk[(String, A)]` | Example values for the OpenAPI spec         |
+| `deprecated` | `Option[Doc]`     | Marks the field as deprecated with a message   |
+| `default`    | `Option[A]`       | Default value (query and header only)          |
+
+To create a query codec with documentation and an example:
+
+```scala
+import zio.blocks.chunk.Chunk
+import zio.blocks.docs.Doc
+import zio.blocks.endpoint._
+import zio.blocks.schema.Schema
+
+val limitCodec = HttpCodec.query(
+  name     = "limit",
+  schema   = Schema.int,
+  default  = Some(20),
+  doc      = Doc.empty,
+  examples = Chunk("default" -> 20, "max" -> 100)
+)
+```