@resapi/core 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@resapi/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Type-safe HTTP contracts for ReScript: endpoint contracts, codecs and a typed client.",
   "license": "MIT",
   "homepage": "https://resapi.dev",

package/src/Client.res

@@ -8,17 +8,19 @@ type t = {
 
 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)
-  | InvalidParams(string)
-  | EncodeFailed(string)
 
-@val external globalFetch: Fetch.Request.t => promise<Fetch.Response.t> = "fetch"
 @val external encodeURIComponent: string => string = "encodeURIComponent"
 
-let make = (~baseUrl, ~fetch=globalFetch, ~headers=dict{}) => {baseUrl, fetch, headers}
+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) => {
@@ -26,13 +28,16 @@ let joinUrl = (baseUrl, path) => {
   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)) => Ok(s)
-  | Some(Number(n)) => Ok(n->Float.toString)
-  | Some(Boolean(b)) => Ok(b ? "true" : "false")
-  | Some(_) => Error(InvalidParams(`Path parameter "${name}" must be a string, number or boolean`))
-  | None => Error(InvalidParams(`Missing path parameter "${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. */
@@ -43,22 +48,20 @@ let buildPath = (path, params: JSON.t) => {
   }
   path
   ->String.split("/")
-  ->Array.reduce(Ok([]), (acc, segment) =>
-    acc->Result.flatMap(segments =>
-      segment->String.startsWith(":")
-        ? paramValue(values, segment->String.slice(~start=1))->Result.map(
-            value => [...segments, encodeURIComponent(value)],
-          )
-        : Ok([...segments, segment])
-    )
+  ->Array.map(segment =>
+    segment->String.startsWith(":")
+      ? encodeURIComponent(paramValue(values, segment->String.slice(~start=1)))
+      : segment
   )
-  ->Result.map(segments => segments->Array.join("/"))
+  ->Array.join("/")
 }
 
-let encodeWith = (encode, value) =>
-  try Ok(encode(value)) catch {
-  | JsExn(e) => Error(EncodeFailed(e->JsExn.message->Option.getOr("Encoding failed")))
-  | _ => Error(EncodeFailed("Encoding failed"))
+// 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 =>
@@ -71,27 +74,44 @@ let decodeResponse = (contract: Endpoint.t<_, _, _, _>, text) =>
   ->Result.flatMap(contract.responseCodec.decode)
   ->Result.mapError(e => InvalidResponse(e))
 
-// A non-2xx body of `{"applicationError": ...}` is a declared error and must decode as one; anything
-// else (framework errors, proxies, plain text) is just an unexpected status.
-let decodeFailure = (contract: Endpoint.t<_, _, _, _>, status, text) =>
-  switch parseJson(text) {
-  | Ok(Object(body)) =>
-    switch body->Dict.get("applicationError") {
-    | Some(json) =>
-      switch contract.errorCodec.decode(json) {
-      | Ok(error) => Error(Application({status, error}))
-      | Error(e) => Error(InvalidResponse({...e, path: ["applicationError", ...e.path]}))
-      }
-    | None => Error(UnexpectedStatus({status, body: text}))
+// 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]}))
     }
-  | _ => Error(UnexpectedStatus({status, body: text}))
+  | 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.readText))
+    Ok((response, await response->Fetch.Response.text))
   } catch {
   | JsExn(e) =>
     switch e->JsExn.name {
@@ -110,20 +130,32 @@ let mergeHeaders = sources => {
   merged
 }
 
-let requestInit = (client, contract: Endpoint.t<_, _, _, _>, body, ~headers, ~signal): result<
-  Fetch.Request.init,
-  _,
-> =>
+let requestInit = (
+  client,
+  contract: Endpoint.t<_, _, _, _>,
+  body,
+  ~headers,
+  ~signal,
+): Fetch.Request.requestInit => {
+  let signal = signal->Option.map(Nullable.make)
   switch contract.method {
-  | Get => Ok({method: "GET", headers: mergeHeaders([client.headers, headers]), ?signal})
-  | Post =>
-    encodeWith(contract.bodyCodec.encode, body)->Result.map((json): Fetch.Request.init => {
+  | Get => {
+      method: "GET",
+      headers: Fetch.HeadersInit.fromDict(mergeHeaders([client.headers, headers])),
+      ?signal,
+    }
+  | Post => {
       method: "POST",
-      headers: mergeHeaders([client.headers, dict{"content-type": "application/json"}, headers]),
-      body: json->JSON.stringify,
+      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,
@@ -133,23 +165,12 @@ let send = async (
   ~headers=dict{},
   ~signal=?,
 ) => {
-  let prepared =
-    encodeWith(contract.paramsCodec.encode, params)
-    ->Result.flatMap(json => buildPath(contract.path, json))
-    ->Result.flatMap(path =>
-      requestInit(client, contract, body, ~headers, ~signal)->Result.map(init => (path, init))
-    )
-  switch prepared {
+  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((path, init)) =>
-    // An invalid baseUrl makes Request throw: a configuration bug, not a request failure.
-    switch await fetchText(client, Fetch.Request.make(joinUrl(client.baseUrl, path), ~init)) {
-    | Error(e) => Error(e)
-    | Ok((response, text)) =>
-      response->Fetch.Response.ok
-        ? decodeResponse(contract, text)
-        : decodeFailure(contract, response->Fetch.Response.status, text)
-    }
+  | Ok((response, text)) =>
+    response.ok ? decodeResponse(contract, text) : decodeFailure(contract, response.status, text)
   }
 }
 
@@ -157,3 +178,13 @@ 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

@@ -2,14 +2,15 @@
 
 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)
-  | InvalidParams(string)
-  | EncodeFailed(string)
 
 /** `~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`.
@@ -23,7 +24,10 @@ let make: (
 /** 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)`. */
+    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>,
@@ -41,3 +45,7 @@ let callWithBody: (
   ~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

@@ -1,6 +1,134 @@
-// The only thing an endpoint needs from a codec. Any backend fits: Sury via @resapi/sury, or a hand-written record.
+// 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}
 
-/** For endpoints without path params or without a request body. */
 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.resi

@@ -8,6 +8,15 @@ 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. */

package/src/Endpoint.res

@@ -53,3 +53,13 @@ let withErrors = (contract: t<'p, 'b, 'r, noError>, errorCodec: Codec.t<'e>, ~st
   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

@@ -32,3 +32,12 @@ let post: (
 
 /** 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

@@ -1,46 +1,97 @@
-// Fetch API bindings shared by the client and server adapters.
+// 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
-
-  /** A signal that aborts after the given number of milliseconds. */
-  @scope("AbortSignal") @val external timeout: int => t = "timeout"
+  @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"
+}
 
-  @new external make: unit => t = "AbortController"
-  @get external signal: t => AbortSignal.t = "signal"
-  @send external abort: t => unit = "abort"
+// 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 Request = {
+module BodyInit = {
   type t
-  type init = {method?: string, headers?: dict<string>, body?: string, signal?: AbortSignal.t}
+  external fromString: string => t = "%identity"
+}
 
-  @new external make: (string, ~init: init=?) => t = "Request"
+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
-  type init = {status?: int, headers?: dict<string>}
-
-  @scope("Response") @val external json: (JSON.t, ~init: init=?) => t = "json"
-  @new external text: (string, ~init: init=?) => t = "Response"
-  @get external status: t => int = "status"
-  @get external ok: t => bool = "ok"
-  @send external readText: t => promise<string> = "text"
-
-  type headers
-  @get external headers: t => headers = "headers"
-  @send @return(nullable) external getHeader: (headers, string) => option<string> = "get"
-
-  /** Mutates in place. Throws on immutable responses, such as one returned by `fetch()`. */
-  @send external setHeader: (headers, string, string) => unit = "set"
-  let setHeader = (response, name, value) => {
-    response->headers->setHeader(name, value)
-    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,
   }
-  let header = (response, name) => response->headers->getHeader(name)
+  @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