@resapi/core 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Seaside Logic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @resapi/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Type-safe HTTP contracts for ReScript: endpoint contracts, codecs and a typed client. Part of [resAPI](https://github.com/Seaside-Logic/resapi).
+
+```sh
+npm install @resapi/core
+```
+
+Add `"@resapi/core"` to `dependencies` in `rescript.json`. Modules are under the `ResApi` namespace.
+
+See the [README](https://github.com/Seaside-Logic/resapi#readme) and [API reference](https://github.com/Seaside-Logic/resapi/blob/main/docs/api.md).

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@resapi/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Type-safe HTTP contracts for ReScript: endpoint contracts, codecs and a typed client.",
+  "license": "MIT",
+  "homepage": "https://resapi.dev",
+  "bugs": {
+    "url": "https://github.com/Seaside-Logic/resapi/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Seaside-Logic/resapi.git",
+    "directory": "packages/core"
+  },
+  "keywords": [
+    "rescript",
+    "http",
+    "api",
+    "contract",
+    "typed-client"
+  ],
+  "type": "module",
+  "files": [
+    "src/*.res",
+    "src/*.resi",
+    "rescript.json"
+  ],
+  "peerDependencies": {
+    "rescript": "^12.3.1"
+  }
+}

package/rescript.json

@@ -0,0 +1,7 @@
+{
+  "name": "@resapi/core",
+  "sources": {"dir": "src"},
+  "package-specs": {"module": "esmodule", "in-source": true},
+  "suffix": ".res.mjs",
+  "namespace": "ResApi"
+}

package/src/Client.res

@@ -0,0 +1,190 @@
+// Calls an endpoint contract over HTTP. Depends only on contracts and Fetch, never on a server adapter.
+
+type t = {
+  baseUrl: string,
+  fetch: Fetch.Request.t => promise<Fetch.Response.t>,
+  headers: dict<string>,
+}
+
+type error<'e> =
+  | Application({status: int, error: 'e})
+  | Unauthorized({status: int, reason: option<string>})
+  | Network(string)
+  | Aborted
+  | UnexpectedStatus({status: int, body: string})
+  | InvalidResponse(Codec.error)
+
+@val external encodeURIComponent: string => string = "encodeURIComponent"
+
+let make = (~baseUrl, ~fetch=request => Fetch.fetchWithRequest(request), ~headers=dict{}) => {
+  baseUrl,
+  fetch,
+  headers,
+}
+
+/** Appends the path to the base URL, keeping any path prefix in the base: `https://x.dev/api/` + `/a` is `https://x.dev/api/a`. */
+let joinUrl = (baseUrl, path) => {
+  let base = baseUrl->String.endsWith("/") ? baseUrl->String.slice(~start=0, ~end=-1) : baseUrl
+  path->String.startsWith("/") ? base ++ path : `${base}/${path}`
+}
+
+// Programmer errors throw: a param that can't fill the path, or a codec that throws. They're bugs in the
+// calling code, and nothing has been sent (like an invalid baseUrl, which makes Request throw).
+let paramValue = (values, name) =>
+  switch values->Dict.get(name) {
+  | Some(JSON.String(s)) => s
+  | Some(Number(n)) => n->Float.toString
+  | Some(Boolean(b)) => b ? "true" : "false"
+  | Some(_) =>
+    JsError.throwWithMessage(`Path parameter "${name}" must be a string, number or boolean`)
+  | None => JsError.throwWithMessage(`Missing path parameter "${name}"`)
+  }
+
+/** Fills `:name` segments from the encoded params object, percent-encoding each value. */
+let buildPath = (path, params: JSON.t) => {
+  let values = switch params {
+  | Object(values) => values
+  | _ => dict{}
+  }
+  path
+  ->String.split("/")
+  ->Array.map(segment =>
+    segment->String.startsWith(":")
+      ? encodeURIComponent(paramValue(values, segment->String.slice(~start=1)))
+      : segment
+  )
+  ->Array.join("/")
+}
+
+// A ReScript exception, or a JS throw of something other than an Error, becomes a JS Error, so the
+// rejected call always carries a message and a stack.
+let encodeOrThrow = (encode, value) =>
+  try encode(value) catch {
+  | JsExn(e) if e->JsExn.message->Option.isSome => JsExn.throw(e)
+  | _ => JsError.throwWithMessage("Encoding failed")
+  }
+
+let parseJson = text =>
+  try Ok(JSON.parseOrThrow(text)) catch {
+  | JsExn(e) => Error({Codec.path: [], message: e->JsExn.message->Option.getOr("Invalid JSON")})
+  }
+
+let decodeResponse = (contract: Endpoint.t<_, _, _, _>, text) =>
+  parseJson(text)
+  ->Result.flatMap(contract.responseCodec.decode)
+  ->Result.mapError(e => InvalidResponse(e))
+
+// The reason a resAPI rejection (the adapters' `Reject`) carries, when this body is one.
+let rejectionReason = json =>
+  switch json {
+  | Ok(JSON.Object(dict{
+      "error": JSON.Object(dict{
+        "kind": JSON.String("unauthenticated" | "forbidden"),
+        "message": JSON.String(message),
+      }),
+    })) if message != "" =>
+    Some(message)
+  | _ => None
+  }
+
+// A declared error (`{"applicationError": ...}`) wins at any status and must decode as one. Otherwise
+// 401 and 403 are Unauthorized, from resAPI's Reject or any other middleware; the rest is unexpected.
+let decodeFailure = (contract: Endpoint.t<_, _, _, _>, status, text) => {
+  let json = parseJson(text)
+  let declared = switch json {
+  | Ok(Object(body)) => body->Dict.get("applicationError")
+  | _ => None
+  }
+  switch declared {
+  | Some(error) =>
+    switch contract.errorCodec.decode(error) {
+    | Ok(error) => Error(Application({status, error}))
+    | Error(e) => Error(InvalidResponse({...e, path: ["applicationError", ...e.path]}))
+    }
+  | None if status == 401 || status == 403 =>
+    Error(Unauthorized({status, reason: rejectionReason(json)}))
+  | None => Error(UnexpectedStatus({status, body: text}))
+  }
+}
+
+// Only the transport is inside the try: codec and status errors are classified elsewhere.
+let fetchText = async (client, request) =>
+  try {
+    let response = await client.fetch(request)
+    Ok((response, await response->Fetch.Response.text))
+  } catch {
+  | JsExn(e) =>
+    switch e->JsExn.name {
+    | Some("AbortError" | "TimeoutError") => Error(Aborted)
+    | _ => Error(Network(e->JsExn.message->Option.getOr("fetch failed")))
+    }
+  }
+
+// Later sources win. Names are lowercased, because Fetch would otherwise combine `Authorization` and
+// `authorization` into one comma-separated value instead of overriding.
+let mergeHeaders = sources => {
+  let merged = dict{}
+  sources->Array.forEach(source =>
+    source->Dict.forEachWithKey((value, name) => merged->Dict.set(name->String.toLowerCase, value))
+  )
+  merged
+}
+
+let requestInit = (
+  client,
+  contract: Endpoint.t<_, _, _, _>,
+  body,
+  ~headers,
+  ~signal,
+): Fetch.Request.requestInit => {
+  let signal = signal->Option.map(Nullable.make)
+  switch contract.method {
+  | Get => {
+      method: "GET",
+      headers: Fetch.HeadersInit.fromDict(mergeHeaders([client.headers, headers])),
+      ?signal,
+    }
+  | Post => {
+      method: "POST",
+      headers: Fetch.HeadersInit.fromDict(
+        mergeHeaders([client.headers, dict{"content-type": "application/json"}, headers]),
+      ),
+      body: Nullable.make(
+        Fetch.BodyInit.fromString(encodeOrThrow(contract.bodyCodec.encode, body)->JSON.stringify),
+      ),
+      ?signal,
+    }
+  }
+}
+
+let send = async (
+  client,
+  contract: Endpoint.t<_, _, _, _>,
+  ~params,
+  ~body,
+  ~headers=dict{},
+  ~signal=?,
+) => {
+  let path = buildPath(contract.path, encodeOrThrow(contract.paramsCodec.encode, params))
+  let init = requestInit(client, contract, body, ~headers, ~signal)
+  switch await fetchText(client, Fetch.Request.fromURL(joinUrl(client.baseUrl, path), ~init)) {
+  | Error(e) => Error(e)
+  | Ok((response, text)) =>
+    response.ok ? decodeResponse(contract, text) : decodeFailure(contract, response.status, text)
+  }
+}
+
+let call = (client, contract, ~params, ~headers=?, ~signal=?) =>
+  send(client, contract, ~params, ~body=(), ~headers?, ~signal?)
+
+let callWithBody = send
+
+let message = (error, ~declared) =>
+  switch error {
+  | Application({error, _}) => declared(error)
+  | Unauthorized({status: 401, _}) => "Please sign in."
+  | Unauthorized(_) => "You don't have permission to do that."
+  | Network(_) => "Can't reach the server. Check your connection and try again."
+  | Aborted => "The request was cancelled."
+  | UnexpectedStatus(_) | InvalidResponse(_) => "Something went wrong. Please try again."
+  }

package/src/Client.resi

@@ -0,0 +1,51 @@
+// Calls an endpoint contract over HTTP. Depends only on contracts and Fetch, never on a server adapter.
+
+type t
+
+/** A declared error (`Application`) wins at any status. Any other 401 or 403 is `Unauthorized`: from
+    resAPI's `Reject` (with its reason) or any other middleware (`reason: None`). */
+type error<'e> =
+  | Application({status: int, error: 'e})
+  | Unauthorized({status: int, reason: option<string>})
+  | Network(string)
+  | Aborted
+  | UnexpectedStatus({status: int, body: string})
+  | InvalidResponse(Codec.error)
+
+/** `~fetch` defaults to the global fetch; pass another to call in-process or to fake a server.
+    `~baseUrl` keeps its path prefix: `https://x.dev/api/` + `/a` is `https://x.dev/api/a`.
+    `~headers` are sent with every request. */
+let make: (
+  ~baseUrl: string,
+  ~fetch: Fetch.Request.t => promise<Fetch.Response.t>=?,
+  ~headers: dict<string>=?,
+) => t
+
+/** For contracts without a request body (`'body = unit`).
+
+    `~headers` override the client's headers and resAPI's `content-type`; names are case-insensitive.
+    Aborting `~signal` (or its timeout firing) ends the call with `Error(Aborted)`.
+
+    Programmer errors reject the promise with a JS Error: a missing or non-scalar path param, a codec that
+    throws, or an invalid baseUrl. Nothing is sent. */
+let call: (
+  t,
+  Endpoint.t<'p, unit, 'r, 'e>,
+  ~params: 'p,
+  ~headers: dict<string>=?,
+  ~signal: Fetch.AbortSignal.t=?,
+) => promise<result<'r, error<'e>>>
+
+/** For contracts with a request body. `~headers` and `~signal` work as in `call`. */
+let callWithBody: (
+  t,
+  Endpoint.t<'p, 'b, 'r, 'e>,
+  ~params: 'p,
+  ~body: 'b,
+  ~headers: dict<string>=?,
+  ~signal: Fetch.AbortSignal.t=?,
+) => promise<result<'r, error<'e>>>
+
+/** A message for showing the user: `declared` for the contract's declared errors, and an English default
+    for the rest. Match the cases you word yourself first, then fall back to this. */
+let message: (error<'e>, ~declared: 'e => string) => string

package/src/Codec.res

@@ -0,0 +1,134 @@
+// The only thing an endpoint needs from a codec. Any backend fits: Sury via @resapi/sury, a hand-written
+// record, or the combinators below.
+type error = {path: array<string>, message: string}
+type t<'a> = {decode: JSON.t => result<'a, error>, encode: 'a => JSON.t}
+
+let unit = {decode: _ => Ok(), encode: () => JSON.Object(dict{})}
+
+let fail = (message): result<_, error> => Error({path: [], message})
+
+// The failed value's position, in front of the inner path: ["2", "role"].
+let under = (segment, error: error) => {...error, path: [segment, ...error.path]}
+
+let string = {
+  decode: json =>
+    switch json {
+    | JSON.String(s) => Ok(s)
+    | _ => fail("Expected string")
+    },
+  encode: s => JSON.String(s),
+}
+
+let float = {
+  decode: json =>
+    switch json {
+    | JSON.Number(n) => Ok(n)
+    | _ => fail("Expected number")
+    },
+  encode: n => JSON.Number(n),
+}
+
+@scope("Number") @val external isSafeInteger: float => bool = "isSafeInteger"
+
+// int is 32-bit: a larger JSON integer is rejected rather than wrapped.
+let int = {
+  decode: json =>
+    switch json {
+    | JSON.Number(n) if isSafeInteger(n) && n >= -2147483648. && n <= 2147483647. =>
+      Ok(n->Float.toInt)
+    | _ => fail("Expected integer")
+    },
+  encode: n => JSON.Number(n->Int.toFloat),
+}
+
+let bool = {
+  decode: json =>
+    switch json {
+    | JSON.Boolean(b) => Ok(b)
+    | _ => fail("Expected boolean")
+    },
+  encode: b => JSON.Boolean(b),
+}
+
+// A linear search: value lists are short, and a lookup object would match inherited keys such as
+// "constructor".
+let enum = (~values, ~toString, ~name="one of the allowed values") => {
+  decode: json =>
+    switch json {
+    | JSON.String(s) =>
+      switch values->Array.find(value => toString(value) == s) {
+      | Some(value) => Ok(value)
+      | None => fail(`Expected ${name}`)
+      }
+    | _ => fail(`Expected ${name}`)
+    },
+  encode: value => JSON.String(toString(value)),
+}
+
+let array = codec => {
+  decode: json =>
+    switch json {
+    | JSON.Array(items) =>
+      items->Array.reduceWithIndex(Ok([]), (acc, item, index) =>
+        acc->Result.flatMap(values =>
+          switch codec.decode(item) {
+          | Ok(value) => Ok([...values, value])
+          | Error(error) => Error(under(index->Int.toString, error))
+          }
+        )
+      )
+    | _ => fail("Expected array")
+    },
+  encode: values => JSON.Array(values->Array.map(codec.encode)),
+}
+
+let option = codec => {
+  decode: json =>
+    switch json {
+    | JSON.Null => Ok(None)
+    | json => codec.decode(json)->Result.map(value => Some(value))
+    },
+  encode: value =>
+    switch value {
+    | None => JSON.Null
+    | Some(value) => codec.encode(value)
+    },
+}
+
+let refine = (codec, check, back) => {
+  decode: json =>
+    codec.decode(json)->Result.flatMap(value =>
+      check(value)->Result.mapError(message => {path: [], message})
+    ),
+  encode: value => codec.encode(back(value)),
+}
+
+type fields = dict<JSON.t>
+
+// Raised by `field` and caught by `object`, so a record decoder reads as a record literal. Never
+// escapes `object`.
+exception FieldError(error)
+
+@scope("Object") @val external hasOwn: (dict<JSON.t>, string) => bool = "hasOwn"
+
+// A missing field decodes as null: `option` fields become None, required ones fail as missing.
+let field = (fields, key, codec) => {
+  let json = hasOwn(fields, key) ? fields->Dict.get(key) : None
+  switch (json, codec.decode(json->Option.getOr(JSON.Null))) {
+  | (_, Ok(value)) => value
+  | (Some(_), Error(error)) => throw(FieldError(under(key, error)))
+  | (None, Error(_)) => throw(FieldError({path: [key], message: "Missing field"}))
+  }
+}
+
+let object = (~decode, ~encode) => {
+  decode: json =>
+    switch json {
+    | JSON.Object(fields) =>
+      try Ok(decode(fields)) catch {
+      | FieldError(error) => Error(error)
+      }
+    | _ => fail("Expected object")
+    },
+  encode: value => JSON.Object(encode(value)->Dict.fromArray),
+}

package/src/Codec.resi

@@ -0,0 +1,44 @@
+// The only thing an endpoint needs from a codec. Any backend fits: Sury via @resapi/sury, a hand-written
+// record, or the combinators below.
+
+/** Where decoding failed (field names and array indexes, outermost first) and why. */
+type error = {path: array<string>, message: string}
+
+type t<'a> = {decode: JSON.t => result<'a, error>, encode: 'a => JSON.t}
+
+/** For endpoints without path params or without a request body. Decodes anything, encodes `{}`. */
+let unit: t<unit>
+
+let string: t<string>
+let float: t<float>
+
+/** Rejects non-integers and values outside the 32-bit range of ReScript's `int`. */
+let int: t<int>
+
+let bool: t<bool>
+
+/** A value from a fixed set, sent as a string. With `@as` variants, `~toString=v => (v :> string)` keeps
+    the wire names in the type and is compiler-checked. List every value in `~values`: a missing one fails
+    to decode, so cover it with a round-trip test. */
+let enum: (~values: array<'a>, ~toString: 'a => string, ~name: string=?) => t<'a>
+
+/** Errors carry the index: `["2", "role"]`. */
+let array: t<'a> => t<array<'a>>
+
+/** `null`, or a missing field inside `object`, is `None`. `None` encodes as `null`. */
+let option: t<'a> => t<option<'a>>
+
+/** Validates or converts after decoding: `Error(message)` fails at this value's path. `back` converts
+    for encoding. */
+let refine: (t<'a>, 'a => result<'b, string>, 'b => 'a) => t<'b>
+
+/** An object's fields, readable only inside `object`'s `~decode`. */
+type fields
+
+/** A field's value. Failures carry the field name in their path; a missing field that isn't an `option`
+    fails as "Missing field". Only call it inside `object`'s `~decode`. */
+let field: (fields, string, t<'a>) => 'a
+
+/** A record codec. Decode by building the record literal from `field`s, so a field left out is a
+    compile error. Encode by listing every field as `(name, json)`. */
+let object: (~decode: fields => 'a, ~encode: 'a => array<(string, JSON.t)>) => t<'a>

package/src/Dispatch.res

@@ -0,0 +1,87 @@
+// The adapter-neutral server pipeline: decodes a request, runs a typed handler and encodes its result
+// in resAPI's wire format. Server adapters supply the raw params and body and send the result.
+// No server or runtime code here.
+
+type input<'params, 'body> = {params: 'params, body: 'body}
+
+type response = {status: int, body: JSON.t}
+
+type rawBody = Text(promise<string>) | Parsed(JSON.t)
+
+let errorResponse = (~status, ~kind, ~message, ~path=[]) => {
+  status,
+  body: JSON.Encode.object(
+    dict{
+      "error": JSON.Encode.object(
+        dict{
+          "kind": JSON.Encode.string(kind),
+          "message": JSON.Encode.string(message),
+          "path": JSON.Encode.array(path->Array.map(JSON.Encode.string)),
+        },
+      ),
+    },
+  ),
+}
+
+// Declared errors travel as `{"applicationError": <encoded>}`, apart from the framework's `{"error": ...}`.
+let applicationErrorResponse = (contract: Endpoint.t<_, _, _, _>, error) => {
+  let status = contract.errorStatus(error)
+  if status < 400 || status > 599 {
+    JsError.throwWithMessage(
+      `Application error status must be 4xx or 5xx, got ${status->Int.toString}`,
+    )
+  }
+  {status, body: JSON.Encode.object(dict{"applicationError": contract.errorCodec.encode(error)})}
+}
+
+let readJsonBody = async (contract: Endpoint.t<_, _, _, _>, readBody) =>
+  switch contract.method {
+  | Get => Ok(JSON.Null)
+  | Post =>
+    switch readBody() {
+    | Parsed(json) => Ok(json)
+    | Text(text) =>
+      // Awaited outside the try: a failed read is unexpected (500), not malformed JSON.
+      let text = await text
+      try Ok(JSON.parseOrThrow(text)) catch {
+      | JsExn(e) => Error(e->JsExn.message->Option.getOr("Invalid JSON"))
+      }
+    }
+  }
+
+// Params are decoded before the body is read, so a bad URL never costs a body parse.
+let respond = async (contract: Endpoint.t<_, _, _, _>, ~params, ~readBody, ~handle) => {
+  let rawParams = JSON.Object(params->Dict.mapValues(s => JSON.String(s)))
+  switch contract.paramsCodec.decode(rawParams) {
+  | Error({path, message}) => errorResponse(~status=400, ~kind="invalid_params", ~message, ~path)
+  | Ok(params) =>
+    switch await readJsonBody(contract, readBody) {
+    | Error(message) => errorResponse(~status=400, ~kind="malformed_json", ~message)
+    | Ok(json) =>
+      switch contract.bodyCodec.decode(json) {
+      | Error({path, message}) => errorResponse(~status=400, ~kind="invalid_body", ~message, ~path)
+      | Ok(body) =>
+        switch await handle({params, body}) {
+        | Ok(response) => {status: 200, body: contract.responseCodec.encode(response)}
+        | Error(error) => applicationErrorResponse(contract, error)
+        }
+      }
+    }
+  }
+}
+
+let run = async (
+  contract: Endpoint.t<'params, 'body, 'response, 'error>,
+  ~params: dict<string>,
+  ~readBody: unit => rawBody,
+  ~handle: input<'params, 'body> => promise<result<'response, 'error>>,
+) =>
+  try await respond(contract, ~params, ~readBody, ~handle) catch {
+  | exn =>
+    // Log the JS Error itself, not ReScript's wrapper, so the stack trace shows.
+    switch exn {
+    | JsExn(e) => Console.error(e)
+    | exn => Console.error(exn)
+    }
+    errorResponse(~status=500, ~kind="internal", ~message="Internal Server Error")
+  }

package/src/Dispatch.resi

@@ -0,0 +1,28 @@
+// The adapter-neutral server pipeline shared by the first-party adapters (@resapi/hono, @resapi/express).
+// Unstable: this is not an extension API for third-party adapters yet, and it may change in any release.
+
+type input<'params, 'body> = {params: 'params, body: 'body}
+
+type response = {status: int, body: JSON.t}
+
+/** The request body, as the adapter has it. `Parsed` is JSON already parsed by framework middleware. */
+type rawBody = Text(promise<string>) | Parsed(JSON.t)
+
+/** The framework error body, `{"error": {"kind", "message", "path"}}`, with its status. The adapters'
+    `Reject` uses it for auth rejections. */
+let errorResponse: (
+  ~status: int,
+  ~kind: string,
+  ~message: string,
+  ~path: array<string>=?,
+) => response
+
+/** `readBody` is called only for POST, after params decode. `handle` must return one of the contract's
+    declared errors. Any exception from a codec, `handle` or reading the body is logged and answered
+    with a 500 that reveals nothing. */
+let run: (
+  Endpoint.t<'params, 'body, 'response, 'error>,
+  ~params: dict<string>,
+  ~readBody: unit => rawBody,
+  ~handle: input<'params, 'body> => promise<result<'response, 'error>>,
+) => promise<response>

package/src/Endpoint.res

@@ -0,0 +1,65 @@
+// A contract describes an endpoint's wire format and is safe to share with clients:
+// it references no server or runtime code. Server adapters turn contracts into routes.
+// Constructors check the route's params against the params codec and throw on a mismatch (RouteCheck).
+
+type method = Get | Post
+
+type noError
+
+type t<'params, 'body, 'response, 'error> = {
+  method: method,
+  path: string,
+  paramsCodec: Codec.t<'params>,
+  bodyCodec: Codec.t<'body>,
+  responseCodec: Codec.t<'response>,
+  errorCodec: Codec.t<'error>,
+  errorStatus: 'error => int,
+}
+
+// Never encodes (no value exists) and never decodes: an error body for such an endpoint is a protocol error.
+let noErrorCodec: Codec.t<noError> = {
+  decode: _ => Error({path: [], message: "This endpoint declares no application errors"}),
+  encode: _ => JSON.Null,
+}
+
+let get = (path, ~params, ~response) => {
+  RouteCheck.assertValid(path, params)
+  {
+    method: Get,
+    path,
+    paramsCodec: params,
+    bodyCodec: Codec.unit,
+    responseCodec: response,
+    errorCodec: noErrorCodec,
+    errorStatus: _ => 500,
+  }
+}
+
+let post = (path, ~params, ~body, ~response) => {
+  RouteCheck.assertValid(path, params)
+  {
+    method: Post,
+    path,
+    paramsCodec: params,
+    bodyCodec: body,
+    responseCodec: response,
+    errorCodec: noErrorCodec,
+    errorStatus: _ => 500,
+  }
+}
+
+let withErrors = (contract: t<'p, 'b, 'r, noError>, errorCodec: Codec.t<'e>, ~status) => {
+  ...contract,
+  errorCodec,
+  errorStatus: status,
+}
+
+type any = {method: method, path: string}
+
+let any = (contract: t<_, _, _, _>) => {method: contract.method, path: contract.path}
+
+let methodName = method =>
+  switch method {
+  | Get => "GET"
+  | Post => "POST"
+  }

package/src/Endpoint.resi

@@ -0,0 +1,43 @@
+// A contract describes an endpoint's wire format and is safe to share with clients: it references no
+// server or runtime code. Server adapters turn contracts into routes.
+
+type method = Get | Post
+
+/** The error type of an endpoint that declares no application errors. It has no values, so a handler
+    for such an endpoint cannot return `Error(_)`. */
+type noError
+
+/** Read-only outside this module: contracts are built with `get`/`post`, which check the route. */
+type t<'params, 'body, 'response, 'error> = private {
+  method: method,
+  path: string,
+  paramsCodec: Codec.t<'params>,
+  bodyCodec: Codec.t<'body>,
+  responseCodec: Codec.t<'response>,
+  errorCodec: Codec.t<'error>,
+  errorStatus: 'error => int,
+}
+
+/** Throws if the route's `:params` don't match the params codec (see `RouteCheck`). Define contracts
+    at module top level, so a mismatch fails at load. */
+let get: (string, ~params: Codec.t<'p>, ~response: Codec.t<'r>) => t<'p, unit, 'r, noError>
+
+/** Throws if the route's `:params` don't match the params codec (see `RouteCheck`). */
+let post: (
+  string,
+  ~params: Codec.t<'p>,
+  ~body: Codec.t<'b>,
+  ~response: Codec.t<'r>,
+) => t<'p, 'b, 'r, noError>
+
+/** Declares the endpoint's application errors and the HTTP status (4xx or 5xx) each one is sent with. */
+let withErrors: (t<'p, 'b, 'r, noError>, Codec.t<'e>, ~status: 'e => int) => t<'p, 'b, 'r, 'e>
+
+/** A contract with its types erased: just the route. Lets contracts of different types share a list,
+    e.g. for an adapter's `assertRegistered`. */
+type any = private {method: method, path: string}
+
+let any: t<'p, 'b, 'r, 'e> => any
+
+/** `"GET"` or `"POST"`. */
+let methodName: method => string

package/src/Fetch.res

@@ -0,0 +1,97 @@
+// A source-compatible subset of @rescript/webapi's Fetch bindings, so code written against ResApi.Fetch
+// keeps compiling when this module becomes re-exports of webapi (planned for ReScript 13).
+//
+// Rule: only names that exist in webapi, with its module paths, labels, argument order, return types and
+// record fields. Leave things out; never change them. resAPI's own conveniences live elsewhere.
+//
+// Mirrored from rescript-lang/experimental-rescript-webapi main as of 2026-10-11 (alpha build b1d58f9):
+// src/fetch/{Request,Response,Headers,HeadersInit,BodyInit,Fetch}.res, src/event/{AbortSignal,
+// AbortController}.res. Re-checked for 0.2.0 against main b46bc2c on 2026-10-11: those files are unchanged.
+// Re-check it at every resAPI release (docs/release-process.md).
+// Abstract types (Headers.t, AbortSignal.t) are subsets of webapi's records: the re-export adds
+// `type t = WebAPI.FetchTypes.headers` and `type t = WebAPI.DOM.abortSignal`.
+
+module AbortSignal = {
+  type t
+  @scope("AbortSignal") external abort: (~reason: JSON.t=?) => t = "abort"
+  @scope("AbortSignal") external timeout: int => t = "timeout"
+  @scope("AbortSignal") external any: array<t> => t = "any"
+}
+
+module AbortController = {
+  type t = private {signal: AbortSignal.t}
+  @new external make: unit => t = "AbortController"
+  @send external abort: (t, ~reason: JSON.t=?) => unit = "abort"
+}
+
+module Headers = {
+  type t
+  @new external make: unit => t = "Headers"
+  @new external fromDict: dict<string> => t = "Headers"
+  @send external append: (t, ~name: string, ~value: string) => unit = "append"
+  @send external delete: (t, string) => unit = "delete"
+  @send external get: (t, string) => Null.t<string> = "get"
+  @send external has: (t, string) => bool = "has"
+  @send external set: (t, ~name: string, ~value: string) => unit = "set"
+}
+
+// Mirrored from webapi: its union-typed init values are bound as abstract types with %identity
+// constructors. The only casts allowed in resAPI (see AGENTS.md).
+module HeadersInit = {
+  type t
+  external fromDict: dict<string> => t = "%identity"
+  external fromHeaders: Headers.t => t = "%identity"
+  external fromKeyValueArray: array<(string, string)> => t = "%identity"
+}
+
+module BodyInit = {
+  type t
+  external fromString: string => t = "%identity"
+}
+
+module Request = {
+  type t = private {
+    method: string,
+    url: string,
+    headers: Headers.t,
+    signal: AbortSignal.t,
+    bodyUsed: bool,
+  }
+  type requestInit = {
+    mutable method?: string,
+    mutable headers?: HeadersInit.t,
+    mutable body?: Nullable.t<BodyInit.t>,
+    mutable signal?: Nullable.t<AbortSignal.t>,
+  }
+  @new external fromURL: (string, ~init: requestInit=?) => t = "Request"
+  @send external json: t => promise<JSON.t> = "json"
+  @send external text: t => promise<string> = "text"
+  @send external clone: t => t = "clone"
+}
+
+module Response = {
+  type t = private {
+    status: int,
+    ok: bool,
+    statusText: string,
+    url: string,
+    redirected: bool,
+    headers: Headers.t,
+    bodyUsed: bool,
+  }
+  type responseInit = {
+    mutable status?: int,
+    mutable statusText?: string,
+    mutable headers?: HeadersInit.t,
+  }
+  @new external fromNull: (@as(json`null`) _, ~init: responseInit=?) => t = "Response"
+  @new external fromString: (string, ~init: responseInit=?) => t = "Response"
+  @scope("Response") external jsonR: (~data: JSON.t, ~init: responseInit=?) => t = "json"
+  @send external json: t => promise<JSON.t> = "json"
+  @send external text: t => promise<string> = "text"
+  @send external clone: t => t = "clone"
+}
+
+external fetch: (string, ~init: Request.requestInit=?) => promise<Response.t> = "fetch"
+external fetchWithRequest: (Request.t, ~init: Request.requestInit=?) => promise<Response.t> =
+  "fetch"

package/src/Key.res

@@ -0,0 +1,13 @@
+// A typed name for a request value: see Key.resi.
+type t<'a> = string
+
+let make = name => name
+
+let name = key => key
+
+let orThrow = (value, key) =>
+  switch value {
+  | Some(value) => value
+  | None =>
+    JsError.throwWithMessage(`No value for key "${key}": is its middleware mounted for this path?`)
+  }

package/src/Key.resi

@@ -0,0 +1,17 @@
+// A typed name for a value that middleware stores on a request and handlers read back, through the
+// adapters' `Context.set/get` (Hono) and `Req.set/get` (Express). The type is a declaration, not a proof:
+// resAPI trusts whoever stored the value to have used this type, as with any external binding.
+
+type t<'a>
+
+/** Annotate the type when you make one: `let userKey: Key.t<User.t> = Key.make("user")`. The name is
+    the framework's own: Hono's `c.set`/`c.get` name, or the property on Express's `req`. So
+    `Key.make("jwtPayload")` reads what hono/jwt sets, and `Key.make("user")` reads Passport's `req.user`. On Express the name is a property on `req`, so don't reuse one
+    of Express's own (`query`, `path`, `params`, `body`...). */
+let make: string => t<'a>
+
+let name: t<'a> => string
+
+/** The value an adapter's `get` found, or a JS Error naming the key when there is none. It backs the
+    adapters' `getOrThrow`, so the message is the same on every adapter. */
+let orThrow: (option<'a>, t<'a>) => 'a

package/src/RouteCheck.res

@@ -0,0 +1,83 @@
+// Checks at contract construction that a route's `:params` and its params codec agree. Works with any
+// Codec.t, without metadata: it probes the codec. Decode an object with every route param set to "x",
+// encode the result back, and compare its keys with the route's params.
+//
+// A codec that refines strings (uuid, int parsing) rejects "x" at a field the route does have. That is
+// inconclusive, not a mismatch: CannotValidate. The decode probe still catches a codec field missing
+// from the route when it is the first error reported, but route params the codec ignores go unnoticed.
+
+type outcome = Valid | Invalid(string) | CannotValidate(string)
+
+let paramName = /^:([A-Za-z_][A-Za-z0-9_]*)$/
+let unsupportedChars = /[:*{}?]/
+
+/** The route's param names, or the first segment this checker doesn't understand
+    (Hono wildcards, regex params, optional params). */
+let parse = (path): result<array<string>, string> =>
+  path
+  ->String.split("/")
+  ->Array.reduce(Ok([]), (acc, segment) =>
+    acc->Result.flatMap(names =>
+      switch paramName->RegExp.exec(segment) {
+      | Some(match) =>
+        switch match[1] {
+        | Some(Some(name)) => Ok([...names, name])
+        | _ => Error(segment)
+        }
+      | None => unsupportedChars->RegExp.test(segment) ? Error(segment) : Ok(names)
+      }
+    )
+  )
+
+let keysOf = (json: JSON.t) =>
+  switch json {
+  | Object(d) => d->Dict.keysToArray
+  | _ => []
+  }
+
+let probe = (names, codec: Codec.t<_>) => {
+  let input = JSON.Object(names->Array.map(n => (n, JSON.String("x")))->Dict.fromArray)
+  switch codec.decode(input) {
+  | Error({path, message})
+    if path->Array.get(0)->Option.mapOr(false, field => names->Array.includes(field)) =>
+    CannotValidate(
+      `params codec rejected the probe value at [${path->Array.join(".")}]: ${message}`,
+    )
+  | Error({path, message}) =>
+    Invalid(
+      `params codec rejected {${names->Array.join(", ")}} at [${path->Array.join(
+          ".",
+        )}]: ${message}`,
+    )
+  | Ok(decoded) =>
+    let keys = keysOf(codec.encode(decoded))
+    let missing = names->Array.filter(n => !(keys->Array.includes(n)))
+    let unexpected = keys->Array.filter(k => !(names->Array.includes(k)))
+    missing == [] && unexpected == []
+      ? Valid
+      : Invalid(
+          `codec lacks [${missing->Array.join(", ")}], route lacks [${unexpected->Array.join(
+              ", ",
+            )}]`,
+        )
+  }
+}
+
+let check = (path, codec) =>
+  switch parse(path) {
+  | Error(segment) =>
+    Invalid(
+      `unsupported route syntax in segment "${segment}" (only literal segments and :name params)`,
+    )
+  | Ok(names) =>
+    switch names->Array.find(n => names->Array.indexOf(n) != names->Array.lastIndexOf(n)) {
+    | Some(name) => Invalid(`duplicate route param :${name}`)
+    | None => probe(names, codec)
+    }
+  }
+
+let assertValid = (path, codec) =>
+  switch check(path, codec) {
+  | Invalid(details) => JsError.throwWithMessage(`Invalid route "${path}": ${details}`)
+  | Valid | CannotValidate(_) => ()
+  }

package/src/RouteCheck.resi

@@ -0,0 +1,10 @@
+// Checks at contract construction that a route's `:params` and its params codec agree.
+
+/** `CannotValidate`: the codec rejected the probe value at a real route param, e.g. because it refines
+    strings. Inconclusive, not a mismatch. */
+type outcome = Valid | Invalid(string) | CannotValidate(string)
+
+let check: (string, Codec.t<'p>) => outcome
+
+/** Throws on Invalid, so a bad top-level contract stops the module (and the Worker) from loading. */
+let assertValid: (string, Codec.t<'p>) => unit