@dual-os/sdk 0.0.0-stage → 0.8.0-next.0

package/src/Http.ts

@@ -0,0 +1,1205 @@
+/**
+ * The HTTP runtime of generated API plugins: each operation's contract and call, request encoding,
+ * response decoding, continuation links, redirects and uploads.
+ *
+ * @since 0.0.0
+ */
+import {
+  Array,
+  Boolean,
+  DateTime,
+  Effect,
+  Equal,
+  Option,
+  Order,
+  Predicate,
+  Random,
+  Record,
+  Result,
+  Schema,
+  SchemaGetter,
+  SchemaIssue,
+  String,
+  flow,
+  pipe,
+} from "effect";
+import type { SchemaAST } from "effect";
+
+import { Base64, Base64Url } from "effect/encoding";
+import {
+  FetchHttpClient,
+  HttpBody,
+  HttpClient,
+  HttpClientError,
+  HttpClientRequest,
+} from "effect/http";
+import type { HttpClientResponse } from "effect/http";
+
+import * as Action from "./Action.ts";
+import type * as AuthMethod from "./AuthMethod.ts";
+import { Files } from "./Files.ts";
+import { Mcp } from "./Mcp.ts";
+import * as ToolFile from "./ToolFile.ts";
+
+function preserveJsonProperties<A, Input>(value: A, input: Input): A {
+  if (Equal.equals(value, input)) return value;
+  if (Array.isArray(value) && Array.isArray(input)) {
+    for (const entry of Array.zip(value, input)) preserveJsonProperties(entry[0], entry[1]);
+  } else if (Predicate.isObject(value) && Predicate.isObject(input)) {
+    for (const entry of Record.toEntries(input)) {
+      if (Record.has(value, entry[0])) {
+        preserveJsonProperties(value[entry[0]], entry[1]);
+      } else {
+        Object.defineProperty(value, entry[0], {
+          configurable: true,
+          enumerable: true,
+          value: entry[1],
+          writable: true,
+        });
+      }
+    }
+  }
+  return value;
+}
+
+function decodeResponse<Output extends Schema.Top>(output: Output) {
+  return flow(
+    Effect.succeed,
+    Effect.flatMap(input =>
+      pipe(
+        Schema.decodeUnknownEffect(output)(input),
+        Effect.map(value => preserveJsonProperties(value, input)),
+      ),
+    ),
+  );
+}
+
+/**
+ * An action's input and output schemas.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export interface Contract {
+  readonly input: Schema.Top;
+  readonly output: Schema.Top;
+}
+
+/**
+ * Runs an action: its input in, its output or a failure out.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export type Handler<Methods extends readonly AuthMethod.Any[], Input, Output> = (
+  input: Input,
+  context: Action.HandlerContext<Methods>,
+) => Effect.Effect<Output, Action.ActionHandlerFailure, HttpClient.HttpClient>;
+
+/**
+ * A file input: a ToolFile as a download returns it, or just its bytes with a type and name.
+ *
+ * @since 0.0.0
+ * @category schemas
+ */
+export type File = typeof File.Type;
+export const File = Schema.Struct({
+  _tag: Schema.optionalKey(Schema.Literal("ToolFile")),
+  contentBase64: Schema.Uint8ArrayFromBase64,
+  contentType: Schema.optionalKey(Schema.NullOr(Schema.String)),
+  filename: Schema.optionalKey(Schema.NullOr(Schema.String)),
+  sizeBytes: Schema.optionalKey(Schema.Natural),
+}).annotate({
+  description:
+    "A ToolFile, such as the result of a download, passed unchanged; or its contentBase64 with an optional contentType and filename.",
+});
+
+const signatures: [string, [number, number[]][]][] = [
+  ["image/jpeg", [[0, [0xff, 0xd8, 0xff]]]],
+  ["image/png", [[0, [0x89, 0x50, 0x4e, 0x47]]]],
+  ["image/gif", [[0, [0x47, 0x49, 0x46, 0x38]]]],
+  [
+    "image/webp",
+    [
+      [0, [0x52, 0x49, 0x46, 0x46]],
+      [8, [0x57, 0x45, 0x42, 0x50]],
+    ],
+  ],
+  ["application/pdf", [[0, [0x25, 0x50, 0x44, 0x46]]]],
+  ["application/zip", [[0, [0x50, 0x4b, 0x03, 0x04]]]],
+];
+
+const utf8 = new TextDecoder("utf-8", { fatal: true });
+
+function sniff(bytes: Uint8Array) {
+  return pipe(
+    Array.findFirst(signatures, signature =>
+      Array.every(signature[1], part =>
+        Array.every(part[1], (byte, index) => bytes[part[0] + index] === byte),
+      ),
+    ),
+    Option.map(signature => signature[0]),
+    Option.orElse(() =>
+      Option.liftPredicate("text/plain", () =>
+        Result.isSuccess(Result.try(() => utf8.decode(bytes))),
+      ),
+    ),
+    Option.getOrNull,
+  );
+}
+
+function toolFile(bytes: Uint8Array, declared: string | null, filename: string | null) {
+  return {
+    _tag: "ToolFile",
+    contentBase64: Base64.encode(bytes),
+    contentType:
+      declared === null || pipe(declared, String.startsWith("application/octet-stream"))
+        ? (sniff(bytes) ?? declared)
+        : declared,
+    filename,
+    sizeBytes: bytes.byteLength,
+  } satisfies ToolFile.File;
+}
+
+function invalid(expected: string, value: unknown, options: SchemaAST.ParseOptions) {
+  return Effect.fail(new SchemaIssue.InvalidValue({ expected }, value, options));
+}
+
+function decodeBytes(text: string, options: SchemaAST.ParseOptions) {
+  return Result.match(
+    Base64Url.decode(pipe(text, String.replaceAll("+", "-"), String.replaceAll("/", "_"))),
+    {
+      onFailure: () => invalid("a Base64 or Base64Url string", text, options),
+      onSuccess: bytes => Effect.succeed(bytes),
+    },
+  );
+}
+
+type Carrier = "base64" | "base64url" | "data-uri";
+
+interface Content {
+  bytes: Uint8Array;
+  contentType: string | null;
+}
+
+function contentOf(carrier: Carrier) {
+  return SchemaGetter.transformEffect<Content, string>((text, options) => {
+    if (carrier !== "data-uri") {
+      return Effect.map(decodeBytes(text, options), bytes => ({ bytes, contentType: null }));
+    }
+    return Option.match(pipe(text, String.match(/^data:([^;,]*)(?:;[^;,]*)*;base64,(.*)$/su)), {
+      onNone: () => invalid("a Base64 data URI", text, options),
+      onSome: parts =>
+        Effect.map(decodeBytes(Array.getUnsafe(parts, 2), options), bytes => ({
+          bytes,
+          contentType: pipe(
+            Array.getUnsafe(parts, 1),
+            Option.liftPredicate(String.isNonEmpty),
+            Option.getOrNull,
+          ),
+        })),
+    });
+  });
+}
+
+function textOf(carrier: Carrier, content: Content) {
+  if (carrier === "base64") return Base64.encode(content.bytes);
+  if (carrier === "base64url") return Base64Url.encode(content.bytes);
+  const contentType = content.contentType ?? sniff(content.bytes) ?? "application/octet-stream";
+  return `data:${contentType};base64,${Base64.encode(content.bytes)}`;
+}
+
+function fileFrom(carrier: Carrier) {
+  return Schema.String.pipe(
+    Schema.decodeTo(ToolFile.Schema, {
+      decode: SchemaGetter.compose(
+        contentOf(carrier),
+        SchemaGetter.transform(content => toolFile(content.bytes, content.contentType, null)),
+      ),
+      encode: SchemaGetter.transformEffect((file: ToolFile.File, options) =>
+        Effect.map(decodeBytes(file.contentBase64, options), bytes =>
+          textOf(carrier, { bytes, contentType: file.contentType }),
+        ),
+      ),
+    }),
+  );
+}
+
+function encodedFrom(carrier: Carrier) {
+  return File.pipe(
+    Schema.decodeTo(Schema.String, {
+      decode: SchemaGetter.transform(file =>
+        textOf(carrier, { bytes: file.contentBase64, contentType: file.contentType ?? null }),
+      ),
+      encode: SchemaGetter.compose(
+        contentOf(carrier),
+        SchemaGetter.transform(content => ({
+          contentBase64: content.bytes,
+          contentType: content.contentType,
+        })),
+      ),
+    }),
+  );
+}
+
+/**
+ * A file the API returns as a Base64 string inside JSON, decoded into a ToolFile with its content
+ * type recognized from the bytes.
+ *
+ * @since 0.0.0
+ * @category schemas
+ */
+export const FileFromBase64 = fileFrom("base64");
+
+/**
+ * {@link FileFromBase64} for an API that writes the file in Base64Url.
+ *
+ * @since 0.0.0
+ * @category schemas
+ */
+export const FileFromBase64Url = fileFrom("base64url");
+
+/**
+ * A {@link File} input the API reads as a Base64 string inside JSON.
+ *
+ * @since 0.0.0
+ * @category schemas
+ */
+export const Base64FromFile = encodedFrom("base64");
+
+/**
+ * {@link Base64FromFile} for an API that reads the file in Base64Url.
+ *
+ * @since 0.0.0
+ * @category schemas
+ */
+export const Base64UrlFromFile = encodedFrom("base64url");
+
+/**
+ * {@link FileFromBase64} for an API that writes the file as a data URI, which also carries its
+ * content type.
+ *
+ * @since 0.0.0
+ * @category schemas
+ */
+export const FileFromDataUri = fileFrom("data-uri");
+
+/**
+ * {@link Base64FromFile} for an API that reads the file as a data URI, built from the file's
+ * content type.
+ *
+ * @since 0.0.0
+ * @category schemas
+ */
+export const DataUriFromFile = encodedFrom("data-uri");
+
+type DateTimeText = typeof DateTimeText.Type;
+const DateTimeText = Schema.String.annotate({ format: "date-time" });
+
+const rfc3339 = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.\d+)?(?:Z|([+-]\d{2}:\d{2}))$/u;
+
+/** The instant of an RFC 3339 date-time with its offset; an impossible date such as February 30 has none. */
+function rfc3339Instant(text: string) {
+  return pipe(
+    Option.fromNullishOr(rfc3339.exec(text)),
+    Option.flatMap(match =>
+      Option.filter(DateTime.makeZoned(text, { timeZone: match[2] ?? "+00:00" }), zoned =>
+        String.startsWith(match[1] ?? "")(DateTime.formatIsoOffset(zoned)),
+      ),
+    ),
+    Option.map(DateTime.toUtc),
+  );
+}
+
+function instants<Wire>(
+  wire: Schema.Codec<Wire>,
+  expected: string,
+  read: (value: Wire) => Option.Option<DateTime.Utc>,
+  write: (instant: DateTime.Utc) => Wire,
+) {
+  const fromWire = SchemaGetter.transformEffect<string, Wire>((value, options) =>
+    Option.match(read(value), {
+      onNone: () => invalid(expected, value, options),
+      onSome: instant => Effect.succeed(DateTime.formatIso(instant)),
+    }),
+  );
+  const toWire = SchemaGetter.transformEffect<Wire, string>((text, options) =>
+    Option.match(rfc3339Instant(text), {
+      onNone: () => invalid("an ISO 8601 date-time", text, options),
+      onSome: instant => Effect.succeed(write(instant)),
+    }),
+  );
+  return {
+    input: pipe(DateTimeText, Schema.decodeTo(wire, { decode: toWire, encode: fromWire })),
+    output: pipe(wire, Schema.decodeTo(DateTimeText, { decode: fromWire, encode: toWire })),
+  };
+}
+
+const unixSeconds = instants(
+  Schema.Int,
+  "Unix seconds",
+  seconds => Option.map(DateTime.make(seconds * 1000), DateTime.toUtc),
+  instant => Math.floor(DateTime.toEpochMillis(instant) / 1000),
+);
+
+const rfc2822 = instants(
+  Schema.String,
+  "an RFC 2822 date-time",
+  text => Option.map(DateTime.make(text), DateTime.toUtc),
+  instant => DateTime.toDateUtc(instant).toUTCString(),
+);
+
+/**
+ * A date-time the API writes as Unix seconds, decoded into an ISO 8601 UTC string.
+ *
+ * @since 0.0.0
+ * @category schemas
+ */
+export const DateTimeFromUnixSeconds = unixSeconds.output;
+
+/**
+ * An ISO 8601 date-time input the API reads as Unix seconds.
+ *
+ * @since 0.0.0
+ * @category schemas
+ */
+export const UnixSecondsFromDateTime = unixSeconds.input;
+
+/**
+ * A date-time the API writes in RFC 2822 form, decoded into an ISO 8601 UTC string.
+ *
+ * @since 0.0.0
+ * @category schemas
+ */
+export const DateTimeFromRfc2822 = rfc2822.output;
+
+/**
+ * An ISO 8601 date-time input the API reads in RFC 2822 form.
+ *
+ * @since 0.0.0
+ * @category schemas
+ */
+export const Rfc2822FromDateTime = rfc2822.input;
+
+/**
+ * An action output whose response decodes into a different shape, such as a file the API sends as
+ * Base64: the action declares the decoded shape and the call decodes the response with `wire`.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export interface Decoded<Wire extends Schema.Top> {
+  readonly _tag: "Decoded";
+  readonly wire: Wire;
+}
+
+/**
+ * Declares an output by the response schema it decodes from; see {@link Decoded}.
+ *
+ * @since 0.0.0
+ * @category constructors
+ */
+export function decoded<const Wire extends Schema.Top>(wire: Wire): Decoded<Wire> {
+  return { _tag: "Decoded", wire };
+}
+
+type Request =
+  | HttpClientRequest.HttpClientRequest
+  | Effect.Effect<HttpClientRequest.HttpClientRequest, Action.ActionHandlerError>;
+
+/** `binary` returns a released version's base64 `ToolFile`; `file` stores the body as a file. */
+type Body = "json" | "text" | "binary" | "file" | "void" | "unknown";
+
+type GraphqlResponse = typeof GraphqlResponse.Type;
+const GraphqlResponse = Schema.Struct({
+  data: Schema.optionalKey(Schema.NullOr(Schema.Record(Schema.String, Schema.Unknown))),
+  errors: Schema.optionalKey(
+    Schema.Array(
+      Schema.StructWithRest(Schema.Struct({ message: Schema.String }), [
+        Schema.Record(Schema.String, Schema.Unknown),
+      ]),
+    ),
+  ),
+});
+
+/**
+ * A response status, media type and decoding mode advertised by an HTTP action.
+ *
+ * @since 0.4.1
+ * @category models
+ */
+export interface Variant {
+  readonly status?: number;
+  readonly contentType: string;
+  readonly body: Body;
+  readonly headers?: readonly string[];
+}
+
+type Media =
+  | { readonly contentBase64: Uint8Array; readonly contentType?: string | null }
+  | Files.File;
+
+type Upload =
+  | { readonly mode: "media"; readonly media: Media }
+  | { readonly mode: "multipart"; readonly media: Media; readonly metadata: unknown }
+  | {
+      readonly mode: "start";
+      readonly contentType: string;
+      readonly metadata?: unknown;
+      readonly totalBytes: number;
+    }
+  | {
+      readonly mode: "chunk";
+      readonly sessionUrl: string;
+      readonly totalBytes: number;
+      readonly offset: number;
+      readonly media: Media;
+    }
+  | { readonly mode: "status"; readonly sessionUrl: string; readonly totalBytes: number };
+
+function coerce(value: unknown) {
+  return Predicate.isObject(value) ? JSON.stringify(value) : `${value}`;
+}
+
+/**
+ * Encodes a path parameter as one segment.
+ *
+ * @since 0.0.0
+ * @category encoding
+ */
+export function path(value: unknown) {
+  return encodeURIComponent(coerce(value));
+}
+
+/**
+ * Encodes a path parameter written inside single quotes, an OData string literal, doubling its
+ * quotes: `O'Brien` in `People('{name}')` is sent as `People('O''Brien')`.
+ *
+ * @since 0.0.0
+ * @category encoding
+ */
+export function literal(value: unknown) {
+  return path(pipe(coerce(value), String.replaceAll("'", "''")));
+}
+
+/**
+ * Encodes a path parameter whose slashes stay path separators.
+ *
+ * @since 0.0.0
+ * @category encoding
+ */
+export function segments(value: unknown) {
+  return Array.join(Array.map(String.split(coerce(value), "/"), encodeURIComponent), "/");
+}
+
+function deepObject(name: string, value: unknown): [string, string][] {
+  if (Array.isArray(value)) {
+    return Array.flatMap(value, (item, index) => deepObject(`${name}[${index}]`, item));
+  }
+  if (Predicate.isObject(value)) {
+    return Array.flatMap(Record.toEntries(value), entry =>
+      deepObject(`${name}[${entry[0]}]`, entry[1]),
+    );
+  }
+  return value === undefined ? [] : [[name, coerce(value)]];
+}
+
+/**
+ * Query, header or form entries, repeating array values unless their name is joined, and encoding
+ * `deep` names as bracketed keys such as `metadata[plan]` and `expand[0]`. A joined name is
+ * comma-separated, or separated by the delimiter it is paired with, such as `["ids", "|"]`.
+ * `exploded` object parameters use their property names as query keys (`role=vet&active=true`).
+ *
+ * @since 0.0.0
+ * @category encoding
+ */
+export function params(
+  fields: Record.ReadonlyRecord<string, unknown>,
+  joined: readonly (string | readonly [string, string])[] = [],
+  deep: readonly string[] = [],
+  exploded: readonly string[] = [],
+) {
+  return Array.flatMap(Record.toEntries(fields), field => {
+    if (field[1] === undefined) return [];
+    if (Array.contains(deep, field[0])) return deepObject(field[0], field[1]);
+    const values = field[1];
+    if (
+      Array.contains(exploded, field[0]) &&
+      Predicate.isObject(values) &&
+      !Array.isArray(values)
+    ) {
+      return Array.filterMap(Record.toEntries(values), entry =>
+        entry[1] === undefined
+          ? Result.failVoid
+          : Result.succeed([entry[0], coerce(entry[1])] as const),
+      );
+    }
+    if (!Array.isArray(values)) return [[field[0], coerce(values)] as const];
+    const separator = Array.findFirst(joined, entry => {
+      const pair = Predicate.isString(entry) ? ([entry, ","] as const) : entry;
+      return pair[0] === field[0] ? Option.some(pair[1]) : Option.none();
+    });
+    return Option.match(separator, {
+      onNone: () => Array.map(values, item => [field[0], coerce(item)] as const),
+      onSome: value => [[field[0], Array.join(Array.map(values, coerce), value)] as const],
+    });
+  });
+}
+
+function filePart(bytes: Uint8Array, name: string, contentType: string) {
+  return new globalThis.File([new Uint8Array(bytes)], name, { type: contentType });
+}
+
+/**
+ * Multipart form fields, sending each {@link File} as a file part.
+ *
+ * @since 0.0.0
+ * @category encoding
+ */
+export function form(payload: Record.ReadonlyRecord<string, unknown>) {
+  return Record.map(payload, (value, name) =>
+    Array.map(Array.ensure(value), item => {
+      if (item === undefined) return undefined;
+      if (!Schema.is(File)(item)) return coerce(item);
+      return filePart(
+        item.contentBase64,
+        item.filename ?? name,
+        item.contentType ?? "application/octet-stream",
+      );
+    }),
+  );
+}
+
+function fileFailed(error: Files.FileError) {
+  return Action.ActionHandlerError.make({ cause: error, message: error.message });
+}
+
+function readFile(file: Files.File) {
+  return pipe(Files.read(file), Effect.mapError(fileFailed));
+}
+
+/**
+ * Sends a file as the raw request body.
+ *
+ * @since 0.1.0
+ * @category encoding
+ */
+export const withFile = Effect.fnUntraced(function* (
+  request: HttpClientRequest.HttpClientRequest,
+  file: Files.File,
+) {
+  return HttpClientRequest.bodyUint8Array(request, yield* readFile(file), file.contentType);
+});
+
+/**
+ * Sends multipart form fields, each {@link Files.File} as a file part.
+ *
+ * @since 0.1.0
+ * @category encoding
+ */
+export const withForm = Effect.fnUntraced(function* (
+  request: HttpClientRequest.HttpClientRequest,
+  payload: Record.ReadonlyRecord<string, unknown>,
+) {
+  return HttpClientRequest.bodyFormDataRecord(
+    request,
+    Record.fromEntries(
+      yield* Effect.forEach(Record.toEntries(payload), field =>
+        Effect.map(
+          Effect.forEach(
+            Array.filter(Array.ensure(field[1]), item => item !== undefined),
+            item =>
+              Effect.gen(function* () {
+                if (!Schema.is(Files.File)(item)) return coerce(item);
+                return filePart(yield* readFile(item), item.name, item.contentType);
+              }),
+          ),
+          parts => [field[0], parts] satisfies [string, (string | globalThis.File)[]],
+        ),
+      ),
+    ),
+  );
+});
+
+function mediaBytes(media: Media) {
+  if (Schema.is(Files.File)(media)) {
+    return Effect.map(readFile(media), bytes => ({ bytes, contentType: media.contentType }));
+  }
+  return Effect.succeed({
+    bytes: media.contentBase64,
+    contentType: Option.getOrNull(Option.fromNullishOr(media.contentType)),
+  });
+}
+
+function isSafeUrl(value: string, origin?: string) {
+  if (!URL.canParse(value)) return false;
+  const url = new URL(value);
+  return (
+    url.protocol === "https:" &&
+    url.username === "" &&
+    url.password === "" &&
+    (origin === undefined || url.origin === origin)
+  );
+}
+
+function refused(message: string) {
+  return Effect.fail(Action.ActionHandlerError.make({ message }));
+}
+
+/**
+ * Follows a returned next-page link on the operation's own origin: only its path and query are
+ * taken, so the connection's host routing applies and credentials never reach another host.
+ *
+ * @since 0.0.0
+ * @category requests
+ */
+export function continuation(request: HttpClientRequest.HttpClientRequest, nextLink?: string) {
+  if (nextLink === undefined) return Effect.succeed(request);
+  const declared = new URL(request.url);
+  const next = URL.canParse(nextLink) ? new URL(nextLink) : undefined;
+  if (next === undefined || !isSafeUrl(nextLink) || next.pathname !== declared.pathname) {
+    return refused("A continuation URL must be an HTTPS link to the same operation path");
+  }
+  return Effect.succeed(
+    HttpClientRequest.make(request.method)(`${declared.origin}${next.pathname}${next.search}`, {
+      headers: request.headers,
+    }),
+  );
+}
+
+/**
+ * A request to a preauthenticated upload URL, which is sent without the connection's credentials.
+ *
+ * @since 0.0.0
+ * @category requests
+ */
+export function preauthenticated(
+  method: (url: string) => HttpClientRequest.HttpClientRequest,
+  url: string,
+  ...steps: readonly ((
+    request: HttpClientRequest.HttpClientRequest,
+  ) => HttpClientRequest.HttpClientRequest)[]
+) {
+  if (!isSafeUrl(url)) return refused("An upload session requires a preauthenticated HTTPS URL");
+  return Effect.succeed(Array.reduce(steps, method(url), (request, step) => step(request)));
+}
+
+function failure(
+  error:
+    | Action.ActionHandlerError
+    | Action.HttpClientFailure
+    | { readonly cause: unknown; readonly response: HttpClientResponse.HttpClientResponse },
+) {
+  return Schema.is(Action.ActionHandlerError)(error) ? error : Action.fromHttpClientFailure(error);
+}
+
+// Like HttpClient.followRedirects, except that a redirect to another origin sends no
+// request header at all: auth methods may set any header, such as GitLab's PRIVATE-TOKEN.
+function redirect(response: HttpClientResponse.HttpClientResponse) {
+  const location = response.headers["location"];
+  if (response.status < 300 || response.status >= 400 || location === undefined) return undefined;
+  const sent = response.request;
+  const url = new URL(location, sent.url);
+  const request =
+    (response.status === 303 && sent.method !== "GET" && sent.method !== "HEAD") ||
+    ((response.status === 301 || response.status === 302) && sent.method === "POST")
+      ? HttpClientRequest.setBody(HttpClientRequest.setMethod(sent, "GET"), HttpBody.empty)
+      : sent;
+  return url.origin === new URL(sent.url).origin
+    ? HttpClientRequest.setUrl(request, url)
+    : HttpClientRequest.make(request.method)(url, { body: request.body });
+}
+
+function follow(
+  client: HttpClient.HttpClient,
+  response: HttpClientResponse.HttpClientResponse,
+  redirects: number,
+): Effect.Effect<HttpClientResponse.HttpClientResponse, HttpClientError.HttpClientError> {
+  const next = redirect(response);
+  return next === undefined || redirects === 10
+    ? Effect.succeed(response)
+    : Effect.flatMap(client.execute(next), result => follow(client, result, redirects + 1));
+}
+
+/** The file name a `Content-Disposition` header suggests, preferring its encoded form. */
+function dispositionName(header?: string) {
+  if (header === undefined) return undefined;
+  const encoded = pipe(
+    String.match(/(?:^|;)\s*filename\*\s*=\s*UTF-8'[^']*'([^;]+)/iu)(header),
+    Option.flatMap(match => Option.fromUndefinedOr(match[1])),
+  );
+  const decoded = pipe(
+    encoded,
+    Option.flatMap(value => Option.liftThrowable(() => decodeURIComponent(String.trim(value)))()),
+  );
+  return Option.getOrElse(decoded, () =>
+    pipe(
+      String.match(/(?:^|;)\s*filename\s*=\s*(?:"((?:\\.|[^"\\])*)"|([^;]*))/iu)(header),
+      Option.flatMap(match =>
+        Option.orElse(
+          Option.map(Option.fromUndefinedOr(match[1]), name =>
+            String.replace(/\\(.)/gu, "$1")(name),
+          ),
+          () => Option.map(Option.fromUndefinedOr(match[2]), String.trim),
+        ),
+      ),
+      Option.getOrUndefined,
+    ),
+  );
+}
+
+const read = Effect.fnUntraced(function* (
+  response: HttpClientResponse.HttpClientResponse,
+  body: Body,
+) {
+  if (body === "json") return yield* response.json;
+  if (body === "text") return yield* response.text;
+  if (body === "void") return {};
+  if (body === "unknown") {
+    const text = yield* response.text;
+    if (String.isEmpty(String.trim(text))) return null;
+    return Option.getOrElse(
+      Schema.decodeOption(Schema.fromJsonString(Schema.Json))(text),
+      () => text,
+    );
+  }
+  const bytes = new Uint8Array(yield* response.arrayBuffer);
+  const name = dispositionName(response.headers["content-disposition"]);
+  if (body === "file") {
+    return yield* pipe(
+      Files.write({
+        bytes,
+        contentType: Option.getOrNull(Option.fromUndefinedOr(response.headers["content-type"])),
+        name: name ?? "file",
+      }),
+      Effect.mapError(fileFailed),
+    );
+  }
+  return toolFile(bytes, response.headers["content-type"] ?? null, name ?? null);
+});
+
+/**
+ * One API operation as {@link make} returns it: its contract and the call that performs it. The
+ * `Context` parameter lets a package name its handler context once, so declaration files print
+ * `Endpoint<Context, …>` instead of repeating its auth methods in every action.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export interface Endpoint<Context, Input extends Schema.Top, Output extends Schema.Top> {
+  readonly input: Input;
+  readonly output: Output;
+  readonly run: (
+    input: Input["Type"],
+    context: Context,
+  ) => Effect.Effect<Output["Type"], Action.ActionHandlerFailure, HttpClient.HttpClient>;
+}
+
+/**
+ * An {@link Endpoint} whose output is the decoded type of the response schema it keeps as `wire`.
+ *
+ * @since 0.0.0
+ * @category models
+ */
+export interface DecodedEndpoint<Context, Input extends Schema.Top, Wire extends Schema.Top> {
+  readonly input: Input;
+  readonly output: Schema.toType<Wire>;
+  readonly wire: Wire;
+  readonly run: (
+    input: Input["Type"],
+    context: Context,
+  ) => Effect.Effect<Wire["Type"], Action.ActionHandlerFailure, HttpClient.HttpClient>;
+}
+
+/**
+ * Binds the runtime to a package's auth module: the calls a generated version file makes. Its
+ * `authorize` applies a connection's credentials to the client. Its optional `checkResponse` fails
+ * a successful response that reports a failed call, such as Slack's `{ ok: false, error }`.
+ * `preauthenticatedUploadUrl` restricts credential-free upload requests and every redirect to
+ * provider-approved HTTPS URLs, without changing authenticated calls or other providers.
+ *
+ * @since 0.0.0
+ * @category constructors
+ */
+export function make<
+  const Methods extends readonly AuthMethod.Any[],
+  Context extends Action.HandlerContext<Methods> = Action.HandlerContext<Methods>,
+>(auth: {
+  readonly authorize: (
+    client: HttpClient.HttpClient,
+    context: Action.HandlerContext<Methods>,
+  ) => HttpClient.HttpClient;
+  readonly checkResponse?: (
+    response: HttpClientResponse.HttpClientResponse,
+  ) => Effect.Effect<void, Action.ActionHandlerError | HttpClientError.HttpClientError>;
+  readonly preauthenticatedUploadUrl?: Schema.Schema<string>;
+}) {
+  const { authorize, checkResponse = () => Effect.void } = auth;
+  const send = Effect.fnUntraced(function* (context: Context | undefined, request: Request) {
+    const base = yield* HttpClient.HttpClient;
+    const uploadPolicy = context === undefined ? auth.preauthenticatedUploadUrl : undefined;
+    const client =
+      uploadPolicy === undefined
+        ? base
+        : HttpClient.mapRequestEffect(base, outgoing =>
+            isSafeUrl(outgoing.url) && Schema.is(uploadPolicy)(outgoing.url)
+              ? Effect.succeed(outgoing)
+              : Effect.fail(
+                  new HttpClientError.HttpClientError({
+                    reason: new HttpClientError.InvalidUrlError({
+                      description: "The upload URL is not an approved provider HTTPS destination",
+                      request: outgoing,
+                    }),
+                  }),
+                ),
+          );
+    const transport = HttpClient.transformResponse(
+      client,
+      Effect.flatMap(response => follow(client, response, 0)),
+    );
+    const authorized = context === undefined ? transport : authorize(transport, context);
+    const execution = authorized.execute(Effect.isEffect(request) ? yield* request : request);
+    const options = yield* Effect.serviceOption(FetchHttpClient.RequestInit);
+    const response = yield* Boolean.match(uploadPolicy !== undefined, {
+      onFalse: () => execution,
+      onTrue: () =>
+        Effect.provideService(execution, FetchHttpClient.RequestInit, {
+          ...Option.getOrElse(options, () => ({})),
+          redirect: "manual",
+        }),
+    });
+    if (response.status < 200 || response.status >= 300) {
+      return yield* Effect.fail({ cause: yield* response.text, response });
+    }
+    yield* checkResponse(response);
+    return response;
+  });
+
+  /**
+   * One API operation: its action contract and the call that performs it. A {@link Decoded} output
+   * declares the decoded shape and hands the call its response schema.
+   */
+  function endpoint<const Input extends Schema.Top, const Output extends Schema.Top>(
+    contract: { readonly input: Input; readonly output: Output },
+    run: (
+      input: Input["Type"],
+      context: Context,
+      output: Output,
+    ) => Effect.Effect<Output["Type"], Action.ActionHandlerFailure, HttpClient.HttpClient>,
+  ): Endpoint<Context, Input, Output>;
+  function endpoint<const Input extends Schema.Top, const Wire extends Schema.Top>(
+    contract: { readonly input: Input; readonly output: Decoded<Wire> },
+    run: (
+      input: Input["Type"],
+      context: Context,
+      output: Wire,
+    ) => Effect.Effect<Wire["Type"], Action.ActionHandlerFailure, HttpClient.HttpClient>,
+  ): DecodedEndpoint<Context, Input, Wire>;
+  function endpoint<const Input extends Schema.Top, const Output extends Schema.Top>(
+    contract: { readonly input: Input; readonly output: Output | Decoded<Output> },
+    run: (
+      input: Input["Type"],
+      context: Context,
+      output: Output,
+    ) => Effect.Effect<Output["Type"], Action.ActionHandlerFailure, HttpClient.HttpClient>,
+  ) {
+    if (!Schema.isSchema(contract.output)) {
+      const wire = contract.output.wire;
+      return {
+        input: contract.input,
+        output: Schema.toType(wire),
+        run: (input: Input["Type"], context: Context) => run(input, context, wire),
+        wire,
+      };
+    }
+    const output = contract.output;
+    return {
+      input: contract.input,
+      output,
+      run: (input: Input["Type"], context: Context) => run(input, context, output),
+    };
+  }
+
+  /** Sends a request and decodes its body as the operation's single response. */
+  function execute<Output extends Schema.Top>(
+    context: Context | undefined,
+    output: Output,
+    request: Request,
+    body: Body,
+  ) {
+    return pipe(
+      send(context, request),
+      Effect.flatMap(response => read(response, body)),
+      Effect.flatMap(decodeResponse(output)),
+      Effect.mapError(failure),
+    );
+  }
+
+  /** Sends a request and decodes the declared response variant its status and media type select. */
+  const variants = Effect.fnUntraced(function* <Output extends Schema.Top>(
+    context: Context | undefined,
+    output: Output,
+    request: Request,
+    declared: readonly Variant[],
+    media?: boolean,
+  ) {
+    const response = yield* send(context, request);
+    const exact = Array.flatMap(declared, variant =>
+      variant.status === undefined ? [] : [variant.status],
+    );
+    const contentType = pipe(
+      response.headers["content-type"] ?? "",
+      String.split(";"),
+      Array.headNonEmpty,
+      String.trim,
+      String.toLowerCase,
+    );
+    const ordered = Array.sort(
+      declared,
+      Order.mapInput(Order.Number, (variant: Variant) => {
+        if (variant.body === "void" || variant.body === "unknown") return 3;
+        if (variant.contentType === "*/*") return 2;
+        return pipe(variant.contentType, String.endsWith("/*")) ? 1 : 0;
+      }),
+    );
+    const variant = Array.findFirst(ordered, candidate => {
+      const status =
+        candidate.status === undefined
+          ? !Array.contains(exact, response.status)
+          : candidate.status === response.status;
+      if (!status) return false;
+      if (media !== undefined) {
+        return (candidate.body === "binary" || candidate.body === "file") === media;
+      }
+      if (
+        candidate.body === "void" ||
+        candidate.body === "unknown" ||
+        candidate.contentType === "*/*"
+      ) {
+        return true;
+      }
+      if (pipe(candidate.contentType, String.endsWith("/*"))) {
+        return pipe(
+          contentType,
+          String.startsWith(pipe(candidate.contentType, String.slice(0, -1))),
+        );
+      }
+      return contentType === candidate.contentType;
+    });
+    if (Option.isNone(variant)) {
+      return yield* Effect.fail({
+        cause: "The API returned an undeclared successful response",
+        response,
+      });
+    }
+    const headers = Array.flatMap(variant.value.headers ?? [], name => {
+      const value = response.headers[String.toLowerCase(name)];
+      return value === undefined ? [] : [[name, value] as const];
+    });
+    return yield* decodeResponse(output)({
+      body: yield* read(response, variant.value.body),
+      contentType: variant.value.contentType,
+      status: response.status,
+      ...(variant.value.headers === undefined ? {} : { headers: Record.fromEntries(headers) }),
+    });
+  }, Effect.mapError(failure));
+
+  /** Google's media, multipart and resumable upload protocols. */
+  const googleUpload = Effect.fnUntraced(function* <Output extends Schema.Top>(
+    context: Context,
+    output: Output,
+    request: HttpClientRequest.HttpClientRequest,
+    payload: Upload,
+    options: { readonly maxSize?: number; readonly resumable?: string },
+  ) {
+    const client = authorize(yield* HttpClient.HttpClient, context);
+    const media = "media" in payload ? yield* mediaBytes(payload.media) : undefined;
+    const size = "totalBytes" in payload ? payload.totalBytes : (media?.bytes.byteLength ?? 0);
+    if (size < 0 || (options.maxSize !== undefined && size > options.maxSize)) {
+      return yield* refused("The upload size is outside the API's declared limit");
+    }
+    const origin = new URL(request.url).origin;
+    if (payload.mode === "start") {
+      if (options.resumable === undefined) {
+        return yield* refused("This API has no resumable upload protocol");
+      }
+      const response = yield* client.execute(
+        pipe(
+          HttpClientRequest.setUrl(request, options.resumable),
+          HttpClientRequest.setUrlParam("uploadType", "resumable"),
+          HttpClientRequest.setHeaders({
+            "x-upload-content-length": `${size}`,
+            "x-upload-content-type": payload.contentType,
+          }),
+          HttpClientRequest.bodyJsonUnsafe(payload.metadata ?? {}),
+        ),
+      );
+      if (response.status < 200 || response.status >= 300) {
+        return yield* Effect.fail({ cause: yield* response.text, response });
+      }
+      const sessionUrl = response.headers["location"];
+      if (sessionUrl === undefined || !isSafeUrl(sessionUrl, origin)) {
+        return yield* Effect.fail({
+          cause: "The API returned an invalid upload session URL",
+          response,
+        });
+      }
+      return yield* decodeResponse(output)({ nextOffset: 0, sessionUrl, state: "pending" });
+    }
+    if (payload.mode === "chunk" || payload.mode === "status") {
+      if (!isSafeUrl(payload.sessionUrl, origin)) {
+        return yield* refused("The upload session URL must use the API's HTTPS origin");
+      }
+      const bytes = media?.bytes ?? new Uint8Array();
+      const end = payload.mode === "chunk" ? payload.offset + bytes.byteLength : 0;
+      if (
+        payload.mode === "chunk" &&
+        (payload.offset < 0 ||
+          bytes.byteLength === 0 ||
+          end > size ||
+          (end < size && bytes.byteLength % 262_144 !== 0))
+      ) {
+        return yield* refused(
+          "Upload chunks must fit the total size and use 256 KiB multiples except for the final chunk",
+        );
+      }
+      const response = yield* client.execute(
+        pipe(
+          HttpClientRequest.put(payload.sessionUrl),
+          HttpClientRequest.bodyUint8Array(bytes, media?.contentType ?? "application/octet-stream"),
+          HttpClientRequest.setHeader(
+            "content-range",
+            payload.mode === "status"
+              ? `bytes */${size}`
+              : `bytes ${payload.offset}-${end - 1}/${size}`,
+          ),
+        ),
+      );
+      if (response.status === 308) {
+        const range = response.headers["range"];
+        if (range !== undefined && !/^bytes=0-\d+$/u.test(range)) {
+          return yield* Effect.fail({
+            cause: "The API returned an invalid upload range",
+            response,
+          });
+        }
+        const nextOffset = range === undefined ? 0 : Number(pipe(range, String.slice(8))) + 1;
+        if (nextOffset > size) {
+          return yield* Effect.fail({
+            cause: "The API returned an upload offset beyond the total size",
+            response,
+          });
+        }
+        return yield* decodeResponse(output)({
+          nextOffset,
+          sessionUrl: payload.sessionUrl,
+          state: "pending",
+        });
+      }
+      if (response.status < 200 || response.status >= 300) {
+        return yield* Effect.fail({ cause: yield* response.text, response });
+      }
+      return yield* decodeResponse(output)({ resource: yield* response.json, state: "complete" });
+    }
+    const selected = HttpClientRequest.setUrlParam(request, "uploadType", payload.mode);
+    const bytes = media?.bytes ?? new Uint8Array();
+    const contentType = media?.contentType ?? "application/octet-stream";
+    const boundary = `dual-${yield* Random.nextInt}-${yield* Random.nextInt}`;
+    const metadata =
+      payload.mode === "multipart"
+        ? yield* Schema.encodeEffect(Schema.fromJsonString(Schema.Unknown))(payload.metadata)
+        : "";
+    const body =
+      payload.mode === "media"
+        ? HttpClientRequest.bodyUint8Array(selected, bytes, contentType)
+        : HttpClientRequest.bodyUint8Array(
+            selected,
+            new Uint8Array(
+              yield* Effect.promise(() =>
+                new Blob([
+                  `--${boundary}\r\nContent-Type: application/json; charset=UTF-8\r\n\r\n${metadata}\r\n--${boundary}\r\nContent-Type: ${contentType}\r\n\r\n`,
+                  new Uint8Array(bytes),
+                  `\r\n--${boundary}--\r\n`,
+                ]).arrayBuffer(),
+              ),
+            ),
+            `multipart/related; boundary=${boundary}`,
+          );
+    const response = yield* client.execute(body);
+    if (response.status < 200 || response.status >= 300) {
+      return yield* Effect.fail({ cause: yield* response.text, response });
+    }
+    return yield* decodeResponse(output)({ resource: yield* response.json, state: "complete" });
+  }, Effect.mapError(failure));
+
+  /** Sends a GraphQL operation and decodes its root field, failing with the errors it returns. */
+  const graphql = Effect.fnUntraced(function* <Output extends Schema.Top>(
+    context: Context,
+    output: Output,
+    request: Request,
+    field: string,
+  ) {
+    const response = yield* send(context, request);
+    const body = yield* Schema.decodeUnknownEffect(GraphqlResponse)(yield* response.json);
+    if (body.errors !== undefined && Array.isReadonlyArrayNonEmpty(body.errors)) {
+      return yield* Action.ActionHandlerError.make({
+        details: body.errors,
+        message: Array.join(
+          Array.map(body.errors, error => error.message),
+          "; ",
+        ),
+      });
+    }
+    return yield* decodeResponse(output)(body.data?.[field]);
+  }, Effect.mapError(failure));
+
+  /**
+   * Calls a Model Context Protocol tool in a session with the server. A tool that reports an error
+   * fails the action with its text; otherwise the output is its structured content, or its content
+   * blocks when it declares no output schema.
+   */
+  const mcp = Effect.fnUntraced(
+    function* <Output extends Schema.Top>(
+      context: Context,
+      output: Output,
+      server: string,
+      tool: string,
+      args: unknown,
+      structured: boolean,
+    ) {
+      const connection = yield* Mcp.connect(
+        authorize(yield* HttpClient.HttpClient, context),
+        server,
+        {},
+      );
+      const result = yield* Schema.decodeUnknownEffect(Mcp.CallToolResult)(
+        yield* connection.request("tools/call", { arguments: args, name: tool }),
+      );
+      if (result.isError === true) {
+        return yield* Action.ActionHandlerError.make({
+          details: result.content,
+          message: Array.join(
+            Array.flatMap(result.content, block => Array.fromNullishOr(block.text)),
+            "\n",
+          ),
+        });
+      }
+      return yield* decodeResponse(output)(
+        Boolean.match(structured, {
+          onFalse: () => ({ content: result.content }),
+          onTrue: () => result.structuredContent,
+        }),
+      );
+    },
+    Effect.scoped,
+    Effect.mapError(error =>
+      Schema.is(Mcp.McpError)(error)
+        ? Action.ActionHandlerError.make({ message: error.message })
+        : failure(error),
+    ),
+  );
+
+  return { endpoint, execute, googleUpload, graphql, mcp, variants };
+}
+
+export * as Http from "./Http.ts";