@gjermundgaraba/effect-actions 0.9.0 → 0.10.0

package/dist/Authentication.mjs

@@ -1,55 +1,248 @@
-import { Effect } from "effect";
+import { Unauthenticated, scopeToken } from "./internal/errors.mjs";
+import { assertOwnTags, errorList } from "./internal/actions.mjs";
+import { declaredResponse } from "./internal/declared.mjs";
+import { answer, answerStepUp, bearer, challenge, isRefusal, isStepUp, plain } from "./internal/refusal.mjs";
+import { Context, Effect, Layer, Match, Option, Predicate, Redacted } from "effect";
 import { HttpEffect, HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/http";
+import { HttpApiBuilder, HttpApiMiddleware, HttpApiSecurity } from "effect/http-api";
 //#region src/Authentication.ts
 /**
-* Authenticate each request and provide its identity to the downstream handler.
-* `authenticate` fails with the response to send instead, so the host owns its
-* status, body and challenge headers. Dependencies remain native router request
-* requirements. Acquired resources live until the request scope closes, including
-* while the handler is running. Every response is marked `Cache-Control: no-store`,
-* including private failures serialized by enclosing middleware.
+* An `Authorization` header of the `Bearer` scheme, and its token, as Effect's own
+* `HttpApiSecurity.bearer` decodes a request's: the scheme, matched case-insensitively, one or
+* more spaces, then the rest of the header, whatever it holds, a tab included. The whitespace
+* around a header value is no part of it, and an HTTP parser strips it before any route reads it.
 */
-const middleware = (service, authenticate) => HttpRouter.middleware()((httpEffect) => authenticate.pipe(Effect.matchEffect({
-	onFailure: Effect.succeed,
-	onSuccess: (identity) => Effect.provideService(httpEffect, service, identity)
-}), HttpEffect.withPreResponseHandler((_request, response) => Effect.succeed(HttpServerResponse.setHeader(response, "cache-control", "no-store")))));
-const quoted = (value) => `"${value.replace(/["\\]/g, "\\$&")}"`;
+const bearerScheme = /^[ \t]*Bearer +(.*[^ \t])[ \t]*$/i;
 /**
-* Publish RFC 9728 discovery independently from the authenticated routes.
-* This supplies metadata and challenges; the host still verifies access tokens.
+* The bearer token of an `Authorization` header, `authorization`, or none, read as Effect's
+* `HttpApiSecurity.bearer` reads it for routes and MCP, which a test holds equal. It is for a
+* caller the router never routes, which holds the header and no request; a route of the host's
+* own is authenticated by `protect`. The scheme is matched case-insensitively, as RFC 9110
+* requires, and the token is `Redacted`, as Effect's own decoder gives it.
 */
-const protectedResource = (options) => {
+const bearerTokenOf = (authorization) => Option.map(Option.fromNullishOr(bearerScheme.exec(authorization ?? "")?.[1]), (token) => Redacted.make(token));
+/**
+* The RFC 9728 metadata URL of `options`: `/.well-known/oauth-protected-resource` followed
+* by the resource's path, where MCP clients look when a 401 names no metadata URL.
+*/
+const metadataUrl = (options) => {
 	const resource = new URL(options.resource);
-	const path = `/.well-known/oauth-protected-resource${resource.pathname === "/" ? "" : resource.pathname}`;
-	const discoveryUrl = new URL(resource);
-	discoveryUrl.pathname = path;
-	const metadataUrl = discoveryUrl.href;
-	const target = metadataUrl.slice(discoveryUrl.origin.length);
-	const response = HttpServerResponse.jsonUnsafe({
+	const url = new URL(resource);
+	url.pathname = `/.well-known/oauth-protected-resource${resource.pathname === "/" ? "" : resource.pathname}`;
+	return url;
+};
+/** What challenges about `options` name. */
+const namedOf = (options) => ({
+	scope: options?.scopesRequired?.join(" "),
+	metadataUrl: options === void 0 ? void 0 : metadataUrl(options).href
+});
+/** Whether a request whose `Authorization` header is `authorization` presented a bearer token. */
+const tokenPresented = (authorization) => Option.isSome(bearerTokenOf(authorization));
+/**
+* The challenge of a 401: `Bearer`, naming the scopes a client requests and the metadata URL
+* where it finds its authorization server. A request that presented a bearer token is told
+* it is invalid, RFC 6750's `invalid_token`, on which a client may refresh its token before
+* it signs in again; one that presented none names no error code.
+*/
+const challengeOf = (named, presented) => bearer([
+	["error", presented ? "invalid_token" : void 0],
+	["scope", named.scope],
+	["resource_metadata", named.metadataUrl]
+]);
+/**
+* Refuse a protected resource that cannot be published, as `layer` and `refusalResponse` both
+* do: one under a scheme other than Bearer (`oauth` false), a `scopesSupported` or
+* `scopesRequired` that is no list of OAuth scope tokens, as `Forbidden` refuses, and a
+* resource with a fragment, which no request URL carries, so its discovery would never answer
+* (RFC 9728). A resource an Effect builds is checked for its scheme alone, and for the rest
+* once built.
+*/
+const assertResource = (oauth, options) => {
+	if (options === void 0) return;
+	if (!oauth) throw new Error("A protected resource is published only for a Bearer scheme");
+	if (Effect.isEffect(options)) return;
+	for (const key of ["scopesSupported", "scopesRequired"]) {
+		const invalid = options[key]?.find((scope) => !scopeToken.test(scope));
+		if (invalid !== void 0) throw new Error(`Invalid scope in ${key}: "${invalid}"`);
+	}
+	if (new URL(options.resource).href.includes("#")) throw new Error(`A protected resource has no fragment: ${options.resource}`);
+};
+/**
+* `response` as the routes of the authentication answer: `no-store` unless it states its
+* own caching, and a 401 challenged with `challenge` unless it names its own.
+*/
+const settle = (response, challenge) => HttpServerResponse.setHeaders(response, {
+	...response.headers["cache-control"] === void 0 ? { "cache-control": "no-store" } : {},
+	...challenge !== void 0 && response.status === 401 && response.headers["www-authenticate"] === void 0 ? { "www-authenticate": challenge } : {}
+});
+/**
+* The response `layer` answers a refusal with, for a caller the router never routes, such as
+* a Node `upgrade` handler admitting a socket: its status, its JSON, `Cache-Control: no-store`
+* and its challenge, an `Unauthenticated`'s `Bearer`, naming `invalid_token` when
+* `authorization` presented a bearer token, or the `insufficient_scope` of a `Forbidden`
+* naming scopes. Given the protected resource `layer` was, every challenge names its metadata
+* URL and a 401's its `scopesRequired`. Under a descriptor of another scheme, it is the JSON
+* and status alone, a 401 naming that scheme. An error `authentication` declares is sent as
+* its endpoints declare it, its JSON with its status. `HttpServerResponse.toWeb` gives it as a
+* web `Response`.
+*/
+const refusalResponse = (error, options) => {
+	const authentication = options?.authentication;
+	const oauth = authentication === void 0 || isBearer(authentication.security);
+	assertResource(oauth, options?.protectedResource);
+	const named = namedOf(options?.protectedResource);
+	const challenge = authentication !== void 0 && !oauth ? schemeChallenge(authentication.security, authentication.name) : challengeOf(named, tokenPresented(options?.authorization));
+	if (!isRefusal(error)) {
+		const response = declaredResponse(authentication?.error ?? [], error);
+		if (response === void 0) throw new Error("Not a refusal, nor an error the authentication declares");
+		return settle(response, challenge);
+	}
+	return settle(oauth ? answer(error, named.metadataUrl) : plain(error), challenge);
+};
+/**
+* Whether a request URL may resolve to a discovery path, which every other request skips
+* parsing: the URL parser copies `.well-known` as it is, removing only a tab or a newline. Node
+* refuses a target holding those before routing; a platform passing one through still parses.
+*/
+const mayDiscover = /\.well-known|[\t\n\r]/;
+/**
+* RFC 9728 discovery of `options` at its metadata URL, as global router middleware: it
+* answers before routing, so no route middleware, authentication included, ever covers it.
+* The metadata is public to every origin, as a browser client needs it after a 401: it
+* carries `Access-Control-Allow-Origin: *`, and discovery answers its own CORS preflight.
+* Where the host's CORS middleware runs before it, that policy answers the preflight and
+* adds its headers to reads, which keep the `*` where it sets no origin.
+*/
+const discovery = (options) => {
+	const discoveryUrl = metadataUrl(options);
+	const target = discoveryUrl.href.slice(discoveryUrl.origin.length);
+	const metadata = HttpServerResponse.jsonUnsafe({
 		resource: options.resource,
 		authorization_servers: options.authorizationServers,
 		bearer_methods_supported: ["header"],
 		scopes_supported: options.scopesSupported,
 		resource_name: options.resourceName
+	}, { headers: { "access-control-allow-origin": "*" } });
+	/** The preflight of a cross-origin read, allowing the headers it asks for. */
+	const preflight = (request) => {
+		const requested = request.headers["access-control-request-headers"];
+		return HttpServerResponse.empty({
+			status: 204,
+			headers: {
+				"access-control-allow-origin": "*",
+				"access-control-allow-methods": "GET, HEAD, OPTIONS",
+				...requested === void 0 ? {} : {
+					"access-control-allow-headers": requested,
+					vary: "Access-Control-Request-Headers"
+				}
+			}
+		});
+	};
+	return (next) => Effect.flatMap(HttpServerRequest.HttpServerRequest, (request) => {
+		const targeted = mayDiscover.test(request.url) && URL.canParse(request.url, discoveryUrl.origin) && new URL(request.url, discoveryUrl.origin).href.slice(discoveryUrl.origin.length) === target;
+		if (targeted && (request.method === "GET" || request.method === "HEAD")) return Effect.succeed(metadata);
+		if (targeted && request.method === "OPTIONS") return Effect.succeed(preflight(request));
+		return next;
 	});
+};
+/**
+* What `layer` answers about the protected resource `options`, written once: its metadata
+* URL, each 401's challenge, to a request that presented a bearer token and to one that did
+* not, and its discovery, none without a resource.
+*/
+const answersOf = (options) => {
+	const named = namedOf(options);
 	return {
-		layer: HttpRouter.middleware((next) => Effect.gen(function* () {
-			const request = yield* HttpServerRequest.HttpServerRequest;
-			const url = new URL(request.url, resource.origin);
-			if ((request.method === "GET" || request.method === "HEAD") && url.href.slice(url.origin.length) === target) return response;
-			return yield* next;
-		}), { global: true }),
-		metadataUrl,
-		/** The `WWW-Authenticate` value; parameter values are quoted and escaped. */
-		challenge: (challenge = {}) => {
-			return `Bearer ${[
-				["resource_metadata", metadataUrl],
-				["error", challenge.error],
-				["error_description", challenge.errorDescription],
-				["scope", challenge.scope]
-			].flatMap(([name, value]) => value === void 0 ? [] : [`${name}=${quoted(value)}`]).join(", ")}`;
-		}
+		metadataUrl: named.metadataUrl,
+		invalid: challengeOf(named, true),
+		anonymous: challengeOf(named, false),
+		published: options === void 0 ? void 0 : discovery(options)
 	};
 };
+/** Whether `security` is the Bearer scheme, the one OAuth challenges and discovery name. */
+const isBearer = (security) => Predicate.isTagged(security, "Http") && security.scheme.toLowerCase() === "bearer";
+/** What an OpenAPI component key may hold, and so a descriptor's name, which is its key. */
+const componentKey = /^[\w.-]+$/;
+/**
+* The challenge of a 401 under a scheme other than Bearer: the scheme an `Http` one names,
+* Basic with its realm, the descriptor's name; an API key has no scheme to name.
+*/
+const schemeChallenge = (security, name) => Match.value(security).pipe(Match.tag("Http", ({ scheme }) => challenge(scheme, [])), Match.tag("Basic", () => challenge("Basic", [["realm", name]])), Match.tag("ApiKey", () => void 0), Match.exhaustive);
+/**
+* Browser-safe declaration shared by clients and remote surfaces: the `identity` it
+* authenticates, by the one native scheme `security`, Bearer unless it names another, such
+* as `HttpApiSecurity.apiKey({ in: "cookie", key: "session" })`. The literal name
+* identifies the provider, like a native Context.Key name, and the scheme's OpenAPI key, so it
+* holds only letters, digits, `_`, `.` and `-`; reuse one name only for one declaration.
+*/
+const make = (name, identity, ...options) => {
+	const security = options[0]?.security ?? HttpApiSecurity.bearer;
+	const error = errorList(options[0]?.error);
+	if (!componentKey.test(name)) throw new Error(`Invalid authentication name: ${JSON.stringify(name)}, not an OpenAPI key`);
+	assertOwnTags(`Authentication "${name}"`, error);
+	if (!Predicate.isTagged(security, "Http") && !Predicate.isTagged(security, "ApiKey") && !Predicate.isTagged(security, "Basic")) throw new Error("Authentication takes one native HttpApiSecurity scheme");
+	return {
+		name,
+		identity,
+		security,
+		error,
+		"~provider": Context.Service(`effect-actions/Authentication/Provider/${name}`),
+		"~middleware": HttpApiMiddleware.Service()(`effect-actions/Authentication/Security/${name}`, { security: { [name]: security } }),
+		"~verified": Context.Service(`effect-actions/Authentication/Verified/${name}`)
+	};
+};
+/** Whether `credential`, as a native scheme decodes it, holds anything: an absent one is empty. */
+const presented = (credential) => Redacted.isRedacted(credential) ? Redacted.value(credential) !== "" : credential.username !== "" || Redacted.value(credential.password) !== "";
+function layer(authentication, verify, options = {}) {
+	const { security } = authentication;
+	const oauth = isBearer(security);
+	const protectedResource = options.protectedResource;
+	assertResource(oauth, protectedResource);
+	const resource = Effect.isEffect(protectedResource) ? Effect.map(protectedResource, (built) => {
+		assertResource(oauth, built);
+		return answersOf(built);
+	}) : Effect.succeed(answersOf(protectedResource));
+	const missing = new Unauthenticated({ message: oauth ? "A bearer token is required." : "A credential is required." });
+	return Layer.effect(authentication["~provider"], Effect.gen(function* () {
+		const router = yield* HttpRouter.HttpRouter;
+		const { metadataUrl, invalid, anonymous, published } = yield* resource;
+		if (published !== void 0) yield* router.addGlobalMiddleware(published);
+		const verifier = Effect.isEffect(verify) ? yield* verify : verify;
+		if (!Predicate.isFunction(verifier)) return yield* Effect.die(/* @__PURE__ */ new Error("Missing verify: pass a verify function, or an Effect building one"));
+		const authenticate = (credential) => presented(credential) ? verifier(credential) : Effect.fail(missing);
+		const failed = HttpEffect.appendPreResponseHandler((_request, response) => Effect.succeed(HttpServerResponse.setHeader(response, "cache-control", "no-store")));
+		const challengeOf = (credential) => !oauth ? schemeChallenge(security, authentication.name) : presented(credential) ? invalid : anonymous;
+		const refuse = (error) => isRefusal(error) ? Effect.succeed(oauth ? answer(error, metadataUrl) : plain(error)) : Effect.suspend(() => {
+			const response = declaredResponse(authentication.error, error);
+			return response === void 0 ? Effect.die(error) : Effect.succeed(response);
+		});
+		const verified = (credential, route, slot) => {
+			const challenge = challengeOf(credential);
+			return Effect.matchEffect(authenticate(credential), {
+				onFailure: refuse,
+				onSuccess: (actor) => Effect.provideService(route, slot, actor)
+			}).pipe(Effect.onError(() => failed), HttpEffect.withPreResponseHandler((_request, response) => Effect.succeed(settle(response, challenge))));
+		};
+		return {
+			descriptor: authentication,
+			middleware: { [authentication.name]: (route, { credential }) => verified(credential, route, authentication.identity) },
+			stepUp: (route) => oauth ? Effect.catchIf(route, isStepUp, (error) => Effect.succeed(answer(error, metadataUrl))) : route,
+			http: ((route, optional) => Effect.flatMap(HttpApiBuilder.securityDecode(security), (credential) => optional && !presented(credential) ? route : verified(credential, oauth ? answerStepUp(route, metadataUrl) : route, authentication["~verified"]))),
+			route: ((route) => Effect.flatMap(HttpApiBuilder.securityDecode(security), (credential) => verified(credential, Effect.catchIf(route, isRefusal, refuse), authentication.identity)))
+		};
+	}));
+}
+/**
+* Native router middleware authenticating a route of the host's own, such as an export, a
+* page frame or a WebSocket upgrade, with `authentication`'s provider, as its actions' routes
+* are: the credential its scheme decodes, verified by the same verifier, and the identity
+* provided to the route. It answers as an action route: a missing or invalid credential with
+* the refusal, every response to the request it authenticates `no-store` unless it states its
+* own caching, and a refusal the route fails with, such as a scope check's `Forbidden`, as its
+* status, JSON and challenge, stepping up under Bearer. The layer requires the provider,
+* `layer(authentication, ...)`. An erased descriptor, `Any`, provides no service the types can
+* name: its identity is `unknown`, which would discharge every request service the route owes.
+*/
+const protect = (authentication) => HttpRouter.middleware()(Effect.map(Effect.service(authentication["~provider"]), (runtime) => (route) => runtime.route(route)));
 //#endregion
-export { middleware, protectedResource };
+export { bearerTokenOf, layer, make, protect, refusalResponse };

package/dist/Testing.d.mts

@@ -1,68 +1,93 @@
-import { ClientOptions } from "./internal/fetchClient.mjs";
-import { Schema } from "effect";
-import { HttpApi, HttpApiGroup } from "effect/http-api";
+import { BuiltIn } from "./internal/errors.mjs";
+import { Call } from "./internal/call.mjs";
+import { Action_d_exports, Any } from "./Action.mjs";
+import { Params } from "./internal/mcp.mjs";
+import { Served } from "./internal/memory.mjs";
+import { Effect, Layer, Schema } from "effect";
+import { Headers, HttpClient, HttpClientError, HttpClientRequest, HttpRouter } from "effect/http";
 //#region src/Testing.d.ts
-/** A web handler, such as `HttpRouter.toWebHandler(routes).handler`. */
-export type Handler = (request: Request) => Promise<Response>;
 /**
- * The native grouped HTTP client, calling `handler` in memory instead of the network.
- * `baseUrl` defaults to `http://localhost`.
+ * The native `HttpClient`, answered by `handler` instead of the network: a web handler the
+ * test serves, which other tests may share, such as
+ * `HttpRouter.toWebHandler(routes.pipe(Layer.provide(HttpServer.layerServices))).handler`,
+ * the routes' platform services provided, as `layer(routes)` provides them itself. It is the
+ * client `layer(routes)` gives, without building anything: the test owns the handler, and
+ * disposes of it.
  */
-export declare const httpClient: <Id extends string, Groups extends HttpApiGroup.Constraint>(api: HttpApi.HttpApi<Id, Groups>, handler: Handler, options?: ClientOptions) => import("effect/Effect").Effect<import("effect/Types").Simplify<{ readonly [Group in Extract<Groups, {
-  readonly topLevel: false;
-}> as HttpApiGroup.Identifier<Group>]: import("effect/http-api/HttpApiClient").Client.GroupByEndpoint<Group, never, never>; } & import("effect/http-api/HttpApiClient").Client.TopLevelMethods<Groups, never, never>>, never, Exclude<Exclude<import("effect/http-api/HttpApiMiddleware").MiddlewareClient<import("effect/http-api/HttpApiEndpoint").Middleware<HttpApiGroup.Endpoints<Groups>>>, import("effect/http/HttpClient").HttpClient>, never>>;
-/** A stateless 2026-07-28 request. */
-export interface McpRequestOptions {
-  readonly url: string | URL;
-  readonly method: string;
-  readonly params?: McpRequestParams;
-  readonly headers?: ConstructorParameters<typeof Headers>[0];
-}
+export declare function layer(handler: (request: Request) => Promise<Response>): Layer.Layer<HttpClient.HttpClient>;
 /**
- * What `JSON.stringify` accepts, not only valid JSON: `undefined` fields are
- * dropped, and tests send malformed arguments on purpose.
+ * The native `HttpClient`, answered in memory by `routes` instead of the network: provide
+ * it to `ActionHttp.client` and to `mcpClient`. The routes are built with this layer and
+ * released with its scope, without request logs. What they still require is this layer's, as
+ * under `HttpRouter.serve`: a builder's services, and a per-request service no middleware of
+ * theirs provides, including one a global middleware reads. The routes keep their real
+ * authentication: a client sends its caller's credential. Provided around it, the test
+ * program shares them. It never requires
+ * the platform services, `FileSystem`, `Path`, `HttpPlatform` and `Etag.Generator`: one
+ * provided around it is the routes' too, and `HttpServer.layerServices`' defaults stand in for
+ * the rest, whose `FileSystem` is a no-op. A relative URL resolves against `http://localhost`.
+ * The client is the layer's own: the program's other HTTP clients get none of its requests,
+ * and it none of theirs.
  */
-export type McpRequestValue = string | number | boolean | null | undefined | ReadonlyArray<McpRequestValue> | {
-  readonly [key: string]: McpRequestValue;
-};
-/** JSON-RPC `params`; `_meta` is merged shallowly over the defaults `mcpRequest` supplies. */
-export interface McpRequestParams {
-  readonly _meta?: {
-    readonly [key: string]: McpRequestValue;
-  };
-  readonly [key: string]: McpRequestValue;
+export declare function layer<A, E, R>(routes: Layer.Layer<A, E, R>): Layer.Layer<HttpClient.HttpClient, E, Exclude<HttpRouter.Request.Without<R> | HttpRouter.Request.Only<"Requires", R> | HttpRouter.Request.Only<"GlobalRequires", R>, Served>>;
+/** Where `mcpClient` sends, and through what client. */
+export interface McpClientOptions {
+  /**
+   * The endpoint, resolved by the `HttpClient`: relative under `layer`. Defaults to `/mcp`,
+   * the default `ActionMcp.layerHttp` path.
+   */
+  readonly url?: string;
+  /** Wraps the native `HttpClient`, as `ActionHttp.client` takes it: a bearer token, say. */
+  readonly transformClient?: (client: HttpClient.HttpClient) => HttpClient.HttpClient;
 }
-/** Build one stateless 2026-07-28 JSON-RPC request, with client metadata defaulted. */
-export declare const mcpRequest: ({ url, method, params, headers: init }: McpRequestOptions) => Request;
-/** One `tools/call` for `mcpCall`: the endpoint, the tool and its arguments. */
-export interface McpCallOptions {
-  readonly url: string | URL;
-  /** The tool name, `mcp.name` of its action. */
-  readonly name: string;
-  /** Defaults to `{}`. Like `params`, it may be malformed on purpose. */
-  readonly arguments?: {
-    readonly [key: string]: McpRequestValue;
-  };
-  readonly headers?: ConstructorParameters<typeof Headers>[0];
+/** Where an `mcpRequest` goes, and with what headers. */
+export interface McpRequestOptions {
+  /**
+   * The endpoint, resolved by the `HttpClient` that sends the request: relative under `layer`.
+   * Defaults to `/mcp`, as `mcpClient`'s does; converting to a web `Request` needs an absolute
+   * one.
+   */
+  readonly url?: string;
+  readonly headers?: Headers.Input;
 }
+declare const McpCallError_base: Schema.Class<McpCallError, Schema.TaggedStruct<"McpCallError", {
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * An answer a client method cannot decode as the action's success or a declared error,
+ * such as the native server's message for invalid arguments or an unknown tool. Its message
+ * holds the answer.
+ */
+export declare class McpCallError extends McpCallError_base {}
+/**
+ * What one call of `A` fails with: a declared error value (the action's own or a built-in one
+ * from the tool, or a refusal from the endpoint's authentication), a `SchemaError` when the
+ * input does not encode or the success does not decode, an `HttpClientError` when the
+ * endpoint could not be reached, or an `McpCallError` for any other answer.
+ */
+type CallError<A extends Any> = A["error"][number]["Type"] | BuiltIn | Schema.SchemaError | HttpClientError.HttpClientError | McpCallError;
+/** Every action of `Actions` as `client.<action>(input)`, calling its tool. */
+export type McpClient<Actions extends ReadonlyArray<Any>> = { readonly [A in Actions[number] as A["name"]]: Call<A, Effect.Effect<A["success"]["Type"], CallError<A>>>; };
 /**
- * A tool call's outcome: the success from `structuredContent`, with the text an action's
- * `mcp.text` field sent before it; or the error text of an `isError` result, parsed as
- * JSON when it is JSON (a declared error, whatever its shape) and kept as the text
- * otherwise (the native server's own message, such as for invalid arguments).
+ * A client of an MCP endpoint served by `ActionMcp.layerHttp`, one method per action calling
+ * its tool with one stateless request, as `ActionHttp.client` calls routes: the input is
+ * encoded with the action's schema, and the success decoded from its structured content. A
+ * declared error the tool returns, the action's own or a refusal, is its decoded value, and so
+ * is a refusal the endpoint's authentication answers with. The argument may be omitted when
+ * `{}` is a valid input. Requires the native `HttpClient`, such as the one `layer` provides.
  */
-export type McpCallResult = {
-  readonly isError: false;
-  readonly value: Schema.Json;
-  readonly text?: string;
-} | {
-  readonly isError: true;
-  readonly error: Schema.Json;
-};
+export declare function mcpClient<const Actions extends ReadonlyArray<Any>>(actions: Actions, options?: McpClientOptions): Effect.Effect<McpClient<Actions>, never, HttpClient.HttpClient>;
 /**
- * Call one tool through `handler` with a stateless 2026-07-28 request and return its
- * outcome. A response that is not an HTTP 200 carrying a tool result, such as an
- * authentication refusal or a JSON-RPC error, throws; use `mcpRequest` to inspect one.
+ * One stateless MCP request of `method` with `params`, as `ActionMcp.layerHttp` serves it,
+ * as the native request value: the JSON-RPC envelope, the 2026-07-28 headers, `mcp-name` from
+ * `params.uri` for `resources/read` and `params.name` otherwise, and the client metadata in
+ * `_meta` are filled in, under any `_meta` given, such as a `progressToken`; the protocol
+ * version is always the request's own. The test sends it: `HttpClient.execute` answers the
+ * response as the endpoint sent it, whatever its status, and `HttpClientRequest.toWebResult`
+ * gives the web `Request` a web handler or `fetch` takes, once `url` is absolute. It is for a test
+ * asserting on what `mcpClient` decodes away, such as `tools/list`, a refusal's challenge, or
+ * a call its types would not send.
  */
-export declare const mcpCall: (handler: Handler, { url, name, headers, arguments: args }: McpCallOptions) => Promise<McpCallResult>;
-//#endregion
+export declare const mcpRequest: (method: string, params?: Params, { headers, url }?: McpRequestOptions) => HttpClientRequest.HttpClientRequest;
+//#endregion
+export type { Params as McpParams };

package/dist/Testing.mjs

@@ -1,91 +1,101 @@
-import { fetchApiClient } from "./internal/fetchClient.mjs";
-import { Option, Predicate, Schema } from "effect";
+import { Refusal } from "./internal/errors.mjs";
+import { assertOnce, projectedErrors } from "./internal/actions.mjs";
+import { inputOf } from "./internal/call.mjs";
+import { defaultPath, statelessRequest } from "./internal/mcp.mjs";
+import { clientOf } from "./internal/memory.mjs";
+import { Context, Effect, FileSystem, Layer, Option, Path, Predicate, Schema, identity } from "effect";
+import { Etag, HttpClient, HttpClientRequest, HttpEffect, HttpPlatform, HttpRouter } from "effect/http";
+import { McpSchema } from "effect/ai";
+import { Sse } from "effect/encoding";
 //#region src/Testing.ts
+function layer(routes) {
+	if (!Layer.isLayer(routes)) return clientOf(routes);
+	return Layer.unwrap(Effect.gen(function* () {
+		const fileSystem = Option.getOrElse(yield* Effect.serviceOption(FileSystem.FileSystem), () => FileSystem.makeNoop({}));
+		const platform = yield* Layer.build(Layer.fresh(Layer.mergeAll(HttpPlatform.layer, Path.layer, Etag.layerWeak).pipe(Layer.provideMerge(Layer.succeed(FileSystem.FileSystem, fileSystem)))));
+		const context = Context.merge(platform, yield* Effect.context());
+		const app = yield* HttpRouter.toHttpEffect(routes).pipe(Effect.provideContext(context));
+		return clientOf(HttpEffect.toWebHandlerWith(context)(app));
+	}));
+}
 /**
-* The native grouped HTTP client, calling `handler` in memory instead of the network.
-* `baseUrl` defaults to `http://localhost`.
+* An answer a client method cannot decode as the action's success or a declared error,
+* such as the native server's message for invalid arguments or an unknown tool. Its message
+* holds the answer.
 */
-const httpClient = (api, handler, options) => fetchApiClient(api, (input, init) => handler(new Request(input, init)), {
-	baseUrl: "http://localhost",
-	...options
-});
-/** Build one stateless 2026-07-28 JSON-RPC request, with client metadata defaulted. */
-const mcpRequest = ({ url, method, params = {}, headers: init }) => {
-	const headers = new Headers(init);
-	headers.set("content-type", "application/json");
-	headers.set("accept", "application/json, text/event-stream");
-	headers.set("mcp-protocol-version", "2026-07-28");
-	headers.set("mcp-method", method);
-	if (Predicate.isString(params.name)) headers.set("mcp-name", params.name);
-	return new Request(url, {
-		method: "POST",
-		headers,
-		body: JSON.stringify({
-			jsonrpc: "2.0",
-			id: 1,
-			method,
-			params: {
-				...params,
-				_meta: Object.assign({
-					"io.modelcontextprotocol/clientCapabilities": {},
-					"io.modelcontextprotocol/clientInfo": {
-						name: "test",
-						version: "0"
-					}
-				}, params._meta, { "io.modelcontextprotocol/protocolVersion": "2026-07-28" })
-			}
-		})
-	});
-};
-/** The JSON-RPC response to a `tools/call`: a tool result or a protocol error. */
-const ToolReply = Schema.Union([Schema.Struct({ result: Schema.Struct({
-	isError: Schema.optionalKey(Schema.Boolean),
-	structuredContent: Schema.optionalKey(Schema.Json),
-	content: Schema.Array(Schema.Struct({
-		type: Schema.String,
-		text: Schema.optionalKey(Schema.String)
-	}))
-}) }), Schema.Struct({ error: Schema.Struct({
+var McpCallError = class extends Schema.TaggedError()("McpCallError", { message: Schema.String }) {};
+/** The text of a block, none of a block of another kind. */
+const textOf = (block) => block?.type === "text" ? block.text : void 0;
+/** The JSON-RPC response to a `tools/call`: the native tool result, or a protocol error. */
+const ToolReply = Schema.Union([Schema.Struct({ result: McpSchema.CallToolResult }), Schema.Struct({ error: Schema.Struct({
 	code: Schema.Finite,
 	message: Schema.String
 }) })]);
 const decodeReply = Schema.decodeUnknownOption(Schema.fromJsonString(ToolReply));
-const parseJson = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Json));
 /**
-* Call one tool through `handler` with a stateless 2026-07-28 request and return its
-* outcome. A response that is not an HTTP 200 carrying a tool result, such as an
-* authentication refusal or a JSON-RPC error, throws; use `mcpRequest` to inspect one.
+* The reply in a response: its body when it is one JSON message, or the last reply among an
+* event stream's events, which notifications may precede.
 */
-const mcpCall = async (handler, { url, name, headers, arguments: args = {} }) => {
-	const response = await handler(mcpRequest({
-		url,
-		method: "tools/call",
-		params: {
+const replyOf = (response, text) => {
+	if (!(response.headers["content-type"] ?? "").startsWith("text/event-stream")) return decodeReply(text);
+	const data = [];
+	Sse.makeParser((event) => {
+		if (Predicate.isTagged(event, "Event")) data.push(event.data);
+	}).feed(text);
+	return Option.fromNullishOr(data.flatMap((message) => Option.toArray(decodeReply(message))).at(-1));
+};
+/** Fail with the value of one of `errors` that `text` holds, or else with `otherwise`. */
+const failWith = (errors, text, otherwise) => Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.toCodecJson(Schema.Union(errors))))(text).pipe(Effect.mapError(() => otherwise), Effect.flatMap(Effect.fail));
+/** The tool call of `action` with `input` on `client`, sending to `url`. */
+const callTool = (client, url, action, input) => {
+	const { name } = action;
+	const other = (answer) => new McpCallError({ message: `MCP tools/call "${name}" ${answer}` });
+	return Effect.gen(function* () {
+		const encoded = yield* Schema.encodeEffect(Schema.toCodecJson(action.input))(input);
+		const response = yield* client.execute(mcpRequest("tools/call", {
 			name,
-			arguments: args
-		},
-		...headers === void 0 ? {} : { headers }
-	}));
-	const body = await response.text();
-	if (response.status !== 200) throw new Error(`MCP tools/call "${name}" answered ${response.status}: ${body}`);
-	const reply = body.split("\n").map((line) => line.replace(/^data:/, "").trim()).flatMap((line) => Option.toArray(decodeReply(line))).at(-1);
-	if (reply === void 0) throw new Error(`MCP tools/call "${name}" had no reply: ${body}`);
-	if ("error" in reply) throw new Error(`MCP tools/call "${name}" failed with ${reply.error.code}: ${reply.error.message}`);
-	const { result } = reply;
-	if (result.isError === true) {
-		const text = result.content.find((content) => content.type === "text")?.text ?? "";
-		return {
-			isError: true,
-			error: Option.getOrElse(parseJson(text), () => text)
-		};
-	}
-	if (result.structuredContent === void 0) throw new Error(`MCP tools/call "${name}" returned no structured content: ${body}`);
-	const [text] = result.content.length > 1 ? result.content : [];
-	return {
-		isError: false,
-		value: result.structuredContent,
-		...text?.text === void 0 ? {} : { text: text.text }
-	};
+			arguments: encoded
+		}, { url }));
+		const text = yield* response.text;
+		if (response.status !== 200) return yield* failWith(Refusal.members, text, other(`answered ${response.status}: ${text}`));
+		const reply = replyOf(response, text);
+		if (Option.isNone(reply)) return yield* Effect.fail(other(`had no reply: ${text}`));
+		if ("error" in reply.value) {
+			const { code, message } = reply.value.error;
+			return yield* Effect.fail(other(`failed with ${code}: ${message}`));
+		}
+		const { result } = reply.value;
+		if (result.isError === true) {
+			const error = textOf(result.content.find((block) => block.type === "text")) ?? "";
+			return yield* failWith(projectedErrors(action), error, other(`returned an error: ${error}`));
+		}
+		if (result.structuredContent === void 0) return yield* Effect.fail(other(`returned no structured content: ${text}`));
+		return yield* Schema.decodeUnknownEffect(Schema.toCodecJson(action.success))(result.structuredContent);
+	});
+};
+function mcpClient(actions, { url = defaultPath, transformClient = identity } = {}) {
+	assertOnce("action", actions);
+	return Effect.map(HttpClient.HttpClient, (native) => {
+		const client = transformClient(native);
+		return Object.fromEntries(actions.map((action) => {
+			return [action.name, (...args) => Effect.flatMap(inputOf(action, args), (input) => callTool(client, url, action, input))];
+		}));
+	});
+}
+/**
+* One stateless MCP request of `method` with `params`, as `ActionMcp.layerHttp` serves it,
+* as the native request value: the JSON-RPC envelope, the 2026-07-28 headers, `mcp-name` from
+* `params.uri` for `resources/read` and `params.name` otherwise, and the client metadata in
+* `_meta` are filled in, under any `_meta` given, such as a `progressToken`; the protocol
+* version is always the request's own. The test sends it: `HttpClient.execute` answers the
+* response as the endpoint sent it, whatever its status, and `HttpClientRequest.toWebResult`
+* gives the web `Request` a web handler or `fetch` takes, once `url` is absolute. It is for a test
+* asserting on what `mcpClient` decodes away, such as `tools/list`, a refusal's challenge, or
+* a call its types would not send.
+*/
+const mcpRequest = (method, params = {}, { headers = {}, url = defaultPath } = {}) => {
+	const { headers: routing, body } = statelessRequest(method, params);
+	return HttpClientRequest.post(url).pipe(HttpClientRequest.setHeaders(headers), HttpClientRequest.setHeaders(routing), HttpClientRequest.bodyJsonUnsafe(body));
 };
 //#endregion
-export { httpClient, mcpCall, mcpRequest };
+export { McpCallError, layer, mcpClient, mcpRequest };