@gjermundgaraba/effect-actions 0.4.1 → 0.6.0

package/README.md

@@ -7,7 +7,6 @@ Effect's own servers and clients underneath.
 ## Looks like this
 
 ```ts
-import { McpProtocol } from "effect/unstable/ai";
 import { Effect, Layer, Schema } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
 import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
@@ -30,11 +29,12 @@ const app = Actions.implement({
 });
 
 export const routes = Layer.mergeAll(
-  Http.layer({}, app),
-  ActionMcp.layerHttp(
-    { protocols: [McpProtocol.v2026_07_28], name: "greetings", version: "1.0.0", path: "/mcp" },
-    app,
-  ),
+  Http.layer([app]),
+  ActionMcp.layerHttp([app], {
+    name: "greetings",
+    version: "1.0.0",
+    path: "/mcp",
+  }),
 );
 ```
 
@@ -42,7 +42,7 @@ Serve `routes` with Effect's `HttpRouter` and you have `POST /api/actions/greeti
 and an MCP tool named `greet` at `/mcp`. The same `app` is also:
 
 ```ts
-const { toolkit, layer } = ActionToolkit.make({}, app); // native Effect AI Toolkit and its handler layer
+const { toolkit, layer } = ActionToolkit.make([app]); // native Effect AI Toolkit and its handler layer
 const cli = ActionCli.group(app); // greetings greet --input '{"name":"Ada"}'
 const remote = ActionCliClient.command(Http, "greetings", "greet"); // same command, over HTTP
 const catalog = ActionCatalog.make(Actions); // offline JSON contract, no handlers acquired
@@ -58,10 +58,13 @@ const greeting = Effect.gen(function* () {
 });
 ```
 
+Code that does not run Effects, such as a browser page, gets the same calls as Promises:
+`await ActionHttpClient.promise(Http, { baseUrl }).greetings.greet({ name: "Ada" })`.
+
 ## Why
 
 - Input, success, and errors are declared once. Routes, tools, commands, clients, OpenAPI, and the catalog are derived from that declaration, so they cannot disagree.
-- A handler may fail only with the errors its action declares. Each surface binds one `before` hook that runs before every handler it serves — on HTTP before the payload is even decoded — so a policy such as scope enforcement is written once per surface and no action of that surface can skip it.
+- A handler may fail only with the errors its action declares. Each surface binds one `before` hook that runs before every handler it serves — after successful input decoding — so a policy such as scope enforcement is written once per surface and no action of that surface can skip it.
 - The pieces are Effect's own. `Http.api` is a native `HttpApi`, so `OpenApi.fromApi`, Swagger, Scalar, and `HttpApiClient` work on it unchanged. MCP is Effect's native `McpServer`, one `Tool` per action, with no SDK runtime dependency.
 - Every action states its `access` (`"read"` or `"write"`, required), so authorization reads the contract instead of a hand-maintained list of mutation names.
 - Build-time services and per-request services are tracked separately in the types. Middleware is per group, so a public group and an authenticated group can share one mount path.
@@ -70,10 +73,10 @@ const greeting = Effect.gen(function* () {
 ## Install
 
 ```sh
-pnpm add @gjermundgaraba/effect-actions effect@4.0.0-rc.116
+pnpm add @gjermundgaraba/effect-actions effect@4.0.0-rc.117
 ```
 
-Add `@effect/platform-node@4.0.0-rc.116` to serve from Node. Every module is a subpath import
+Add `@effect/platform-node@4.0.0-rc.117` to serve from Node. Every module is a subpath import
 (`.../Action`, `.../ActionHttp`, ...); there is no package root, so a contracts-only bundle
 never loads a server.
 
@@ -98,13 +101,13 @@ in `node_modules/@gjermundgaraba/effect-actions/docs`) gives the same content.
 
 ## Status
 
-The `effect` peer is pinned to an exact Effect 4 release candidate and moves with it; expect a
-release of this package for each Effect release candidate it adopts. Actions are unary JSON over HTTP and MCP: no streaming, uploads, prompts, or resources.
+The `effect` peer accepts any Effect 4.0 release candidate from `4.0.0-rc.116` on; the package
+is built and tested against the release candidate in its `devDependencies` (see [docs/setup.md](docs/setup.md)). Actions are unary JSON over HTTP and MCP: no streaming, uploads, prompts, or resources.
 Authentication and authorization belong to the application. See [docs/setup.md](docs/setup.md).
 
 ## Acknowledgements
 
-A few idea (like the native Toolkit, CLI, and catalog projections) are inspired by the excellent [rat-stack](https://github.com/joelhooks/rat-stack) by Joel Hooks.
+A few ideas (like the native Toolkit, CLI, and catalog projections) are inspired by the excellent [rat-stack](https://github.com/joelhooks/rat-stack) by Joel Hooks.
 
 ## Contributing
 

package/dist/ActionCatalog.d.mts

@@ -2,7 +2,7 @@ import { Action_d_exports, Any } from "./Action.mjs";
 import { ActionGroup_d_exports, Any as Any$1 } from "./ActionGroup.mjs";
 import { JsonSchema } from "effect";
 //#region src/ActionCatalog.d.ts
-/** One contract, with independently rooted JSON schemas for its encoded values. */
+/** One contract, with independently rooted descriptions of its encoded values. */
 export interface Entry {
   readonly id: string;
   readonly group: string;
@@ -19,7 +19,7 @@ export interface Entry {
 }
 /** An offline contract document, not an authorization decision or a mounted endpoint. */
 export interface Catalog {
-  readonly version: "1";
+  readonly version: "3";
   readonly actions: ReadonlyArray<Entry>;
 }
 /**

package/dist/ActionCatalog.mjs

@@ -1,12 +1,13 @@
-import { assertDistinct } from "./internal/actions.mjs";
+import { assertDistinct, policyErrors } from "./internal/actions.mjs";
 import { JsonSchema, Schema } from "effect";
 //#region src/ActionCatalog.ts
-const jsonSchema = (codec) => {
-	const document = Schema.toJsonSchemaDocument(codec);
+/** Describe the JSON wire form; decoding on the server remains authoritative. */
+const describe = (codec) => {
+	const { schema, definitions } = Schema.toJsonSchemaDocument(codec);
 	return {
 		$schema: JsonSchema.META_SCHEMA_URI_DRAFT_2020_12,
-		...document.schema,
-		...Object.keys(document.definitions).length === 0 ? {} : { $defs: document.definitions }
+		...schema,
+		...Object.keys(definitions).length === 0 ? {} : { $defs: definitions }
 	};
 };
 /**
@@ -17,7 +18,7 @@ const jsonSchema = (codec) => {
 const make = (...groups) => {
 	assertDistinct("catalog group", groups.map((group) => group.name));
 	return {
-		version: "1",
+		version: "3",
 		actions: groups.flatMap((group) => group.actions.map((action) => ({
 			id: `${group.name}.${action.name}`,
 			group: group.name,
@@ -25,10 +26,10 @@ const make = (...groups) => {
 			description: action.description,
 			http: action.http,
 			mcp: action.mcp,
-			input: jsonSchema(action.input),
-			success: jsonSchema(action.success),
-			errors: action.errors.map(jsonSchema),
-			httpSchemaErrors: action.http ? group.schemaError?.errors.map(jsonSchema) ?? [] : []
+			input: describe(action.input),
+			success: describe(action.success),
+			errors: action.errors.map(describe),
+			httpSchemaErrors: action.http && group.schemaError !== void 0 ? policyErrors(group.schemaError).map(describe) : []
 		})))
 	};
 };

package/dist/ActionCli.d.mts

@@ -6,8 +6,8 @@ import { Effect, Scope } from "effect";
 import { Command } from "effect/unstable/cli";
 //#region src/ActionCli.d.ts
 /**
- * The hook a local command runs before the selected handler. A CLI encodes
- * nothing, so its refusal is a typed failure of the command effect rather than a
+ * The hook a local command runs before the selected handler. A CLI does not serialize
+ * failures, so its refusal is a typed failure of the command effect rather than a
  * declared surface error; the native parser has already decoded the input.
  */
 interface BeforeOptions<E, R> {

package/dist/ActionCli.mjs

@@ -1,26 +1,25 @@
+import { selectNamed } from "./internal/actions.mjs";
 import { dispatch } from "./internal/implementation.mjs";
 import { command as command$1 } from "./internal/cli.mjs";
 import { Effect } from "effect";
 import { Command } from "effect/unstable/cli";
 //#region src/ActionCli.ts
-const select = (group, name) => {
-	const action = group.actions.find((candidate) => candidate.name === name);
-	if (action === void 0) throw new Error(`Unknown action "${group.name}.${name}"`);
-	return action;
-};
+/**
+* Acquire the implementation in a scope of its own, run one action through the hook
+* and its handler, and release it: every local command, selected or grouped.
+*/
 const local = (app, action, before, input) => Effect.scoped(Effect.flatMap(app.build, (handlers) => dispatch(app.group, action, handlers, before)(input)));
 /**
 * Project one explicitly selected local action into a native Effect CLI command.
 * The action name resolves against the bound group; no HTTP fallback exists.
 */
 const command = (app, name, options) => {
-	const action = select(app.group, name);
+	const action = selectNamed(app.group.actions, name, `action "${app.group.name}.${name}"`);
 	return command$1(action, (input) => local(app, action, options?.before, input), options);
 };
 /** Project every local action below its group namespace with default CLI options. */
 const group = (app, options) => {
-	const before = options?.before;
-	const commands = app.group.actions.map((action) => command$1(action, (input) => Effect.scoped(Effect.flatMap(app.build, (handlers) => dispatch(app.group, action, handlers, before)(input)))));
+	const commands = app.group.actions.map((action) => command$1(action, (input) => local(app, action, options?.before, input)));
 	return Command.make(options?.name ?? app.group.name).pipe(Command.withSubcommands(commands));
 };
 //#endregion

package/dist/ActionCliClient.d.mts

@@ -1,5 +1,6 @@
 import { Action_d_exports, Codec } from "./Action.mjs";
 import { Actions } from "./internal/actions.mjs";
+import { ServedNames } from "./internal/implementation.mjs";
 import { Options as Options$1 } from "./internal/cli.mjs";
 import { ActionHttp_d_exports, Api, Http } from "./ActionHttp.mjs";
 import { Effect } from "effect";
@@ -7,17 +8,21 @@ import { HttpClient } from "effect/unstable/http";
 import { HttpApi, HttpApiClient, HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
 import { Command } from "effect/unstable/cli";
 //#region src/ActionCliClient.d.ts
+/**
+ * What the host configures on Effect's native client: `baseUrl`, `transformClient`,
+ * `transformResponse`. The selectors and the client are the command's own.
+ */
+export type Connection = NonNullable<globalThis.Parameters<typeof HttpApiClient.make>[1]>;
 /** Parsing, rendering and native HTTP-endpoint configuration for one remote action. */
 export type Options<Output, ParsedParameters extends Command.Command.Config = never> = Options$1<Output, ParsedParameters> & {
-  /** Passed directly to Effect's native `HttpApiClient.endpoint`. */
-  readonly connection?: NonNullable<globalThis.Parameters<typeof HttpApiClient.make>[1]>;
+  readonly connection?: Connection;
 };
 /** Configuration for a remote aggregate group command. */
 export interface GroupOptions {
   /** Override the group command name. */
   readonly name?: string;
   /** Shared native HTTP-endpoint configuration for every remote action. */
-  readonly connection?: NonNullable<globalThis.Parameters<typeof HttpApiClient.make>[1]>;
+  readonly connection?: Connection;
 }
 type Group<Groups extends ReadonlyArray<Actions>, Name extends Groups[number]["name"]> = Extract<Groups[number], {
   readonly name: Name;
@@ -25,9 +30,7 @@ type Group<Groups extends ReadonlyArray<Actions>, Name extends Groups[number]["n
 type Selected<G extends Actions, Name extends G["actions"][number]["name"]> = Extract<G["actions"][number], {
   readonly name: Name;
 }>;
-type HttpNames<G extends Actions> = Extract<G["actions"][number], {
-  readonly http: true;
-}>["name"];
+type HttpNames<G extends Actions> = ServedNames<G, "http">;
 type ApiGroups<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec>> = Api<Groups[number], Errors[number]> extends HttpApi.HttpApi<"actions", infer ApiGroups> ? ApiGroups : never;
 type Endpoint<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec>, GroupName extends Groups[number]["name"], ActionName extends HttpNames<Group<Groups, GroupName>>> = Extract<HttpApiGroup.EndpointsWithIdentifier<ApiGroups<Groups, Errors>, Extract<GroupName, HttpApiGroup.Identifier<ApiGroups<Groups, Errors>>>>, {
   readonly identifier: ActionName;

package/dist/ActionCliClient.mjs

@@ -1,3 +1,4 @@
+import { selectNamed } from "./internal/actions.mjs";
 import { command as command$1 } from "./internal/cli.mjs";
 import { Effect } from "effect";
 import { HttpClient } from "effect/unstable/http";
@@ -12,14 +13,11 @@ import { Command } from "effect/unstable/cli";
 const erasedApi = (api) => {
 	return api;
 };
-const selectGroup = (groups, name) => {
-	const group = groups.find((candidate) => candidate.name === name);
-	if (group === void 0) throw new Error(`Unknown HTTP group "${name}"`);
-	return group;
-};
+/** An action hidden from HTTP is unknown to this binding, exactly like a missing one. */
 const selectAction = (group, name) => {
-	const action = group.actions.find((candidate) => candidate.name === name);
-	if (action === void 0 || !action.http) throw new Error(`Unknown HTTP action "${group.name}.${name}"`);
+	const what = `HTTP action "${group.name}.${name}"`;
+	const action = selectNamed(group.actions, name, what);
+	if (!action.http) throw new Error(`Unknown ${what}`);
 	return action;
 };
 /**
@@ -28,14 +26,14 @@ const selectAction = (group, name) => {
 * keep dynamically supplied selector strings from reaching the native client.
 */
 const command = (http, groupName, actionName, options) => {
-	const group = selectGroup(http.groups, groupName);
+	const group = selectNamed(http.groups, groupName, `HTTP group "${groupName}"`);
 	const action = selectAction(group, actionName);
 	return command$1(action, (input) => Effect.flatMap(HttpClient.HttpClient, (httpClient) => {
 		const endpoint = HttpApiClient.endpoint(erasedApi(http.api), {
+			...options?.connection,
 			group: groupName,
 			endpoint: actionName,
-			httpClient,
-			...options?.connection
+			httpClient
 		});
 		return Effect.flatMap(endpoint, (method) => {
 			return method({ payload: input });
@@ -44,7 +42,7 @@ const command = (http, groupName, actionName, options) => {
 };
 /** Project all HTTP-enabled actions retained by one group below its group namespace. */
 const group = (http, groupName, options) => {
-	const actions = selectGroup(http.groups, groupName);
+	const actions = selectNamed(http.groups, groupName, `HTTP group "${groupName}"`);
 	const commands = actions.actions.flatMap((action) => action.http ? [options?.connection === void 0 ? command(http, groupName, action.name) : command(http, groupName, action.name, { connection: options.connection })] : []);
 	return Command.make(options?.name ?? actions.name).pipe(Command.withSubcommands(commands));
 };

package/dist/ActionGroup.d.mts

@@ -1,37 +1,39 @@
 import { Action, Action_d_exports, Any as Any$1, Codec, Handler } from "./Action.mjs";
-import { Actions, SchemaErrorPolicy } from "./internal/actions.mjs";
+import { Actions, SchemaErrorAnswer, SchemaErrorPolicy } from "./internal/actions.mjs";
 import { Implementation } from "./internal/implementation.mjs";
-import { Effect, Scope } from "effect";
+import { Effect, Scope, Types } from "effect";
 declare namespace ActionGroup_d_exports {
-  export { Any, Contracts, Group, Implementation, Options, SchemaErrorPolicy, contracts, make };
+  export { Any, Contracts, Group, Implementation, Options, SchemaErrorAnswer, SchemaErrorPolicy, contracts, make };
 }
 type HandlersFrom<Actions extends ReadonlyArray<Any$1>> = { readonly [A in Actions[number] as A["name"]]: Handler<A, any>; };
 /** Group-level errors join each action's own, so a shared set is declared once. */
 type WithErrors<Actions extends ReadonlyArray<Any$1>, Errors extends ReadonlyArray<Codec>> = { readonly [K in keyof Actions]: Actions[K] extends Action<infer Name, infer Input, infer Output, infer Own, infer Access, infer Http, infer Mcp> ? Action<Name, Input, Output, readonly [...Own, ...Errors], Access, Http, Mcp> : never; };
 /** What `make` needs to define a group. */
-export interface Options<Name extends string, Errors extends ReadonlyArray<Codec>, PolicyErrors extends ReadonlyArray<Codec>> {
+export interface Options<Name extends string, Errors extends ReadonlyArray<Codec>, Invalid extends Codec = never, Internal extends Codec = never> {
   /** The `HttpApiGroup` identifier, and so the OpenAPI tag and operation-ID prefix. */
   readonly name: Name;
   /** Failures every action of the group may have, added to each action's own. */
   readonly errors?: Errors;
-  /** How HTTP answers failed decoding or encoding of these actions; MCP keeps its native answers. */
-  readonly schemaError?: SchemaErrorPolicy<PolicyErrors>;
+  /**
+   * How HTTP answers a request that fails decoding (`invalid`) and a result that fails
+   * encoding (`internal`); without one, both are Effect's empty 400. MCP keeps its
+   * native answers.
+   */
+  readonly schemaError?: SchemaErrorPolicy<Invalid, Internal>;
 }
 /** A named set of action contracts: what adapters serve and what `implement` binds. */
-export interface Group<Name extends string, Actions$1 extends ReadonlyArray<Any$1>, PolicyErrors extends ReadonlyArray<Codec> = ReadonlyArray<Codec>> extends Actions<Name, Actions$1, PolicyErrors> {
+export interface Group<Name extends string, Actions$1 extends ReadonlyArray<Any$1>, PolicyError extends Codec = Codec> extends Actions<Name, Actions$1, PolicyError> {
   /** Bind every handler at once, resolving build-time services once per adapter layer. */
-  readonly implement: <H extends HandlersFrom<Actions$1>, EX = never, RX = never>(build: H | Effect.Effect<H, EX, RX>) => Implementation<Group<Name, Actions$1, PolicyErrors>, H, NoInfer<EX>, NoInfer<Exclude<RX, Scope.Scope>>>;
+  readonly implement: <H extends HandlersFrom<Actions$1>, EX = never, RX = never>(build: H | Effect.Effect<H, EX, RX>) => Implementation<Group<Name, Actions$1, PolicyError>, H, NoInfer<EX>, NoInfer<Exclude<RX, Scope.Scope>>>;
 }
 /** Any group, with its actions and error schemas erased. */
-export type Any = Group<string, ReadonlyArray<Any$1>, ReadonlyArray<Codec>>;
+export type Any = Group<string, ReadonlyArray<Any$1>, Codec>;
 /** Define a group. Invalid or duplicate action and MCP names fail here, at definition time. */
-export declare function make<const Name extends string, const Actions extends ReadonlyArray<Any$1>, const Errors extends ReadonlyArray<Codec> = [], const PolicyErrors extends ReadonlyArray<Codec> = []>(options: Options<Name, Errors, PolicyErrors>, ...actions: Actions): Group<Name, WithErrors<Actions, Errors>, PolicyErrors>;
+export declare function make<const Name extends string, const Actions extends ReadonlyArray<Any$1>, const Errors extends ReadonlyArray<Codec> = [], Invalid extends Codec = never, Internal extends Codec = never>(options: Options<Name, Errors, Invalid, Internal>, ...actions: Actions): Group<Name, WithErrors<Actions, Errors>, Invalid | Internal>;
 /** `G extends unknown` distributes, so each group maps only its own actions. */
 type PerGroup<G extends Actions> = G extends unknown ? { readonly [A in G["actions"][number] as `${G["name"]}.${A["name"]}`]: A; } : never;
-/** Merges those per-group maps into one, rather than leaving a union of them. */
-type Merged<Maps> = (Maps extends unknown ? (map: Maps) => void : never) extends ((map: infer Merged) => void) ? Merged : never;
-/** Every action of `Groups`, keyed `<group>.<action>`. */
-export type Contracts<Groups extends ReadonlyArray<Actions>> = Merged<PerGroup<Groups[number]>>;
+/** Every action of `Groups`, keyed `<group>.<action>`: the per-group maps merged into one. */
+export type Contracts<Groups extends ReadonlyArray<Actions>> = Types.UnionToIntersection<PerGroup<Groups[number]>>;
 /**
  * Project groups into one map of their action contracts, keyed `<group>.<action>`:
  * the identity routes, tools and commands share. Deriving it from the groups
@@ -39,4 +41,4 @@ export type Contracts<Groups extends ReadonlyArray<Actions>> = Merged<PerGroup<G
  */
 export declare function contracts<const Groups extends ReadonlyArray<Actions>>(...groups: Groups): Contracts<Groups>;
 //#endregion
-export { ActionGroup_d_exports, type Implementation, type SchemaErrorPolicy };
+export { ActionGroup_d_exports, type Implementation, type SchemaErrorAnswer, type SchemaErrorPolicy };

package/dist/ActionGroup.mjs

@@ -2,6 +2,17 @@ import { assertDistinct, assertName } from "./internal/actions.mjs";
 import { Implementation } from "./internal/implementation.mjs";
 import { Effect } from "effect";
 //#region src/ActionGroup.ts
+/**
+* The types require every handler, but a record built in plain JavaScript or through a
+* cast may still lack one, or hold `undefined` under its key. It fails before anything is served rather than on the
+* first request for the missing action.
+*/
+const assertHandlers = (group, handlers) => {
+	const bound = new Map(Object.entries(handlers));
+	const missing = group.actions.filter((action) => bound.get(action.name) === void 0);
+	if (missing.length > 0) throw new Error(`Missing handlers for group "${group.name}": ${missing.map((action) => action.name).join(", ")}`);
+	return handlers;
+};
 function make(options, ...declared) {
 	const { name } = options;
 	assertName("action group name", name);
@@ -16,7 +27,7 @@ function make(options, ...declared) {
 		actions,
 		schemaError: options.schemaError,
 		implement: (build) => {
-			const built = Effect.isEffect(build) ? build : Effect.succeed(build);
+			const built = Effect.isEffect(build) ? Effect.map(build, (handlers) => assertHandlers(group, handlers)) : Effect.succeed(assertHandlers(group, build));
 			return Implementation.make(group, built);
 		}
 	};

package/dist/ActionHttp.d.mts

@@ -24,10 +24,9 @@ export interface Options<Errors extends ReadonlyArray<Codec> = []> {
 /** What `Http.layer` binds around the implementations it serves. */
 export interface LayerOptions<Errors extends ReadonlyArray<Codec>, R> {
   /**
-   * Runs once per request, before the request payload is decoded, with the action
-   * contract it is about to run. It fails with the binding's own `errors`, so an
-   * unauthorized caller learns nothing about the action's input, and the refusal
-   * is encoded exactly like a declared error. Its services are request-time
+   * Runs once after successful payload decoding, before the selected handler,
+   * with its action contract. It fails with the binding's own `errors`, encoded
+   * exactly like a declared error. Its services are request-time
    * requirements, like a handler's.
    */
   readonly before?: (action: Any) => Effect.Effect<void, Errors[number]["Type"], R>;
@@ -48,7 +47,13 @@ export interface Http<Groups extends ReadonlyArray<Actions>, Errors extends Read
    * around every request they answer. Build failures, build services and request
    * services are unions over precisely those apps and that hook.
    */
-  readonly layer: <const Apps extends ReadonlyArray<AnyImplementation<Groups[number]>>, RB = never>(options: LayerOptions<Errors, RB>, ...apps: Apps) => Layer.Layer<never, BuildError<Apps[number]>, BuildContext<Apps[number]> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", RequestContext<Apps[number]> | RB> | Etag.Generator | FileSystem | HttpPlatform.HttpPlatform | Path>;
+  readonly layer: <const Apps extends ReadonlyArray<AnyImplementation<Groups[number]>>, RB = never>(apps: readonly [...Apps], options?: LayerOptions<Errors, RB>) => Layer.Layer<never, BuildError<Apps[number], "http">, BuildContext<Apps[number], "http"> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", RequestContext<Apps[number], "http"> | RB> | Etag.Generator | FileSystem | HttpPlatform.HttpPlatform | Path>;
+  /**
+   * Serve the OpenAPI document of `api` with `GET path`, by default
+   * `<apiPath>/openapi.json`. It is a plain route: middleware provided to this layer
+   * covers it, and none is applied otherwise.
+   */
+  readonly openApi: (path?: HttpRouter.PathInput) => Layer.Layer<never, never, HttpRouter.HttpRouter>;
 }
 /**
  * Bind the contract-level configuration once. Every route is `POST

package/dist/ActionHttp.mjs

@@ -1,7 +1,7 @@
-import { assertDistinct, projectedErrors } from "./internal/actions.mjs";
+import { answerSchemaError, assertDistinct, policyErrors, projectedErrors } from "./internal/actions.mjs";
 import { dispatch } from "./internal/implementation.mjs";
 import { Effect, Layer } from "effect";
-import { HttpEffect, HttpRouter, HttpServerResponse } from "effect/unstable/http";
+import { HttpRouter, HttpServerResponse } from "effect/unstable/http";
 import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, OpenApi } from "effect/unstable/httpapi";
 //#region src/ActionHttp.ts
 const httpActions = (group) => group.actions.filter((action) => action.http);
@@ -12,42 +12,24 @@ const endpoint = (options, group, action) => HttpApiEndpoint.post(action.name, `
 }).annotate(OpenApi.Description, action.description);
 /** The native middleware declares the policy's errors on every endpoint it wraps. */
 const schemaErrorMiddleware = (name, policy) => {
-	class SchemaErrors extends HttpApiMiddleware.Service()(`effect-actions/http/SchemaErrors/${name}`, { error: policy.errors }) {}
+	class SchemaErrors extends HttpApiMiddleware.Service()(`effect-actions/http/SchemaErrors/${name}`, { error: policyErrors(policy) }) {}
 	return {
 		SchemaErrors,
-		layer: HttpApiMiddleware.layerSchemaErrorTransform(SchemaErrors, (failure) => Effect.fail(policy.map(failure)))
-	};
-};
-/** The hook of one group, applied to every one of its endpoints. */
-const hookMiddleware = (name) => {
-	class Admission extends HttpApiMiddleware.Service()(`effect-actions/http/Admission/${name}`) {}
-	const implementation = (group, before) => {
-		if (before === void 0) return (httpEffect) => httpEffect;
-		const actions = new Map(httpActions(group).map((action) => [action.name, action]));
-		return (httpEffect, { endpoint }) => {
-			const action = actions.get(endpoint.identifier);
-			if (action === void 0) throw new Error(`Missing action: ${endpoint.identifier}`);
-			return Effect.flatMap(before(action), () => httpEffect);
-		};
-	};
-	return {
-		Admission,
-		layer: (group, before) => Layer.succeed(Admission, implementation(group, before))
+		layer: HttpApiMiddleware.layerSchemaErrorTransform(SchemaErrors, (failure) => Effect.fail(answerSchemaError(policy, failure)))
 	};
 };
 function bind(options, group) {
 	const [first, ...rest] = httpActions(group).map((action) => endpoint(options, group, action));
 	if (first === void 0) return void 0;
 	const bound = HttpApiGroup.make(group.name).add(first, ...rest);
-	const hook = hookMiddleware(group.name);
 	if (group.schemaError === void 0) return {
-		native: bound.middleware(hook.Admission),
-		middleware: (before) => hook.layer(group, before)
+		native: bound,
+		middleware: Layer.empty
 	};
 	const policy = schemaErrorMiddleware(group.name, group.schemaError);
 	return {
-		native: bound.middleware(policy.SchemaErrors).middleware(hook.Admission),
-		middleware: (before) => Layer.merge(policy.layer, hook.layer(group, before))
+		native: bound.middleware(policy.SchemaErrors),
+		middleware: policy.layer
 	};
 }
 function apiOf(groups) {
@@ -66,22 +48,20 @@ const erasedHandlers = (handlers) => {
 	return handlers;
 };
 /** Register one group's handlers. Handler erasure is limited to native dynamic endpoint registration. */
-const groupHandlers = (api, app, middleware) => {
-	const entries = (record) => Object.fromEntries(httpActions(app.group).map((action) => [action.name, (request) => dispatch(app.group, action, record, void 0)(request.payload)]));
+const groupHandlers = (api, app, middleware, before) => {
+	const entries = (record) => Object.fromEntries(httpActions(app.group).map((action) => {
+		const run = dispatch(app.group, action, record, before);
+		return [action.name, (request) => run(request.payload)];
+	}));
 	return Layer.unwrap(Effect.map(app.build, (record) => HttpApiBuilder.group(api, app.group.name, (builder) => builder.handleAll(entries(erasedHandlers(record)))))).pipe(Layer.provide(middleware));
 };
-/**
-* A refused or failed request is never stored by a shared cache. Successful
-* responses keep whatever the host sets, since only the host knows what is public.
-*/
-const noStore = HttpRouter.middleware((httpEffect) => HttpEffect.withPreResponseHandler(httpEffect, (_request, response) => Effect.succeed(response.status < 400 ? response : HttpServerResponse.setHeader(response, "cache-control", "no-store"))));
 function make(options, ...groups) {
 	assertDistinct("action group", groups.map((group) => group.name));
 	const bound = new Map(groups.flatMap((group) => {
 		const binding = bind(options, group);
 		return binding === void 0 ? [] : [[group, binding]];
 	}));
-	const layer = (layerOptions, ...apps) => {
+	const layer = (apps, layerOptions = {}) => {
 		assertDistinct("implementation group", apps.map((app) => app.group.name));
 		for (const app of apps) if (!groups.includes(app.group)) throw new Error(`Implementation of group "${app.group.name}" is not served by this adapter`);
 		const served = apps.flatMap((app) => {
@@ -92,13 +72,16 @@ function make(options, ...groups) {
 			}];
 		});
 		const api = apiOf(served.map(({ native }) => native));
-		const before = layerOptions.before;
-		return served.reduce((layer, { app, middleware }) => layer.pipe(Layer.provide(groupHandlers(api, app, middleware(before)))), HttpApiBuilder.layer(api)).pipe(Layer.provide(noStore.layer));
+		const [first, ...rest] = served.map(({ app, middleware }) => groupHandlers(api, app, middleware, layerOptions.before));
+		return first === void 0 ? HttpApiBuilder.layer(api) : HttpApiBuilder.layer(api).pipe(Layer.provide([first, ...rest]));
 	};
+	const api = apiOf([...bound.values()].map(({ native }) => native));
+	const openApi = (path = `${options.apiPath}/openapi.json`) => HttpRouter.add("GET", path, HttpServerResponse.jsonUnsafe(OpenApi.fromApi(api)));
 	return {
 		groups,
-		api: apiOf([...bound.values()].map(({ native }) => native)),
-		layer
+		api,
+		layer,
+		openApi
 	};
 }
 //#endregion

package/dist/ActionHttpClient.d.mts

@@ -0,0 +1,45 @@
+import { Action_d_exports, Any, Codec } from "./Action.mjs";
+import { Actions } from "./internal/actions.mjs";
+import { ServedNames } from "./internal/implementation.mjs";
+import { ActionHttp_d_exports, Http } from "./ActionHttp.mjs";
+//#region src/ActionHttpClient.d.ts
+/** Where and how a Promise client sends its requests. */
+export interface Options {
+  /**
+   * What the binding's routes are resolved against, such as `https://api.example.com`.
+   * Omitted, routes stay relative, which a browser resolves against the page's origin.
+   */
+  readonly baseUrl?: string | URL;
+  /** Sent as `Authorization: Bearer <token>` with every call. */
+  readonly token?: string;
+  /**
+   * The transport. Defaults to the global `fetch`, looked up per call. Wrap it to add
+   * headers or to observe responses, such as a proxy's 401.
+   */
+  readonly fetch?: typeof globalThis.fetch;
+}
+/** The HTTP-served actions of `G`: an action with a literal `http: false` has no method. */
+type HttpAction<G extends Actions> = Extract<G["actions"][number], {
+  readonly name: ServedNames<G, "http">;
+}>;
+/**
+ * One action as a Promise of its decoded success. An action whose input may be empty,
+ * such as one declared without `input`, may be called without an argument.
+ */
+export type Method<A extends Any> = {} extends A["input"]["Type"] ? (input?: A["input"]["Type"]) => Promise<A["success"]["Type"]> : (input: A["input"]["Type"]) => Promise<A["success"]["Type"]>;
+/** Every HTTP-served action of the binding, as `client.<group>.<action>(input)`. */
+export type Client<Groups extends ReadonlyArray<Actions>> = { readonly [G in Groups[number] as [HttpAction<G>] extends [never] ? never : G["name"]]: { readonly [A in HttpAction<G> as A["name"]]: Method<A>; }; };
+/**
+ * A Promise client for an HTTP binding, for code that does not run Effects, such as a
+ * browser page. It is Effect's native `HttpApiClient` over `fetch`, built once, and
+ * each call runs one request: nothing is retried.
+ *
+ * A call resolves with the action's decoded success. It rejects with what the native
+ * client fails with: a declared error value (the action's, its group's schema-error
+ * policy's, or the binding's surface `errors`), a native `HttpClientError` when the
+ * server could not be reached or answered with a status or body the contract does not
+ * declare, or a `SchemaError` when the input does not encode or the success does not
+ * decode.
+ */
+export declare function promise<const Groups extends ReadonlyArray<Actions>, const Errors extends ReadonlyArray<Codec>>(http: Http<Groups, Errors>, options?: Options): Client<Groups>;
+//#endregion

package/dist/ActionHttpClient.mjs

@@ -0,0 +1,24 @@
+import { Effect } from "effect";
+import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/unstable/http";
+import { HttpApiClient } from "effect/unstable/httpapi";
+//#region src/ActionHttpClient.ts
+function promise(http, { baseUrl, token, fetch } = {}) {
+	const send = fetch ?? ((input, init) => globalThis.fetch(input, init));
+	const native = Effect.runSync(HttpApiClient.make(http.api, {
+		baseUrl,
+		transformClient: token === void 0 ? void 0 : HttpClient.mapRequest(HttpClientRequest.bearerToken(token))
+	}).pipe(Effect.provide(FetchHttpClient.layer), Effect.provideService(FetchHttpClient.Fetch, send)));
+	return Object.fromEntries(http.groups.flatMap((group) => {
+		const endpoints = native[group.name];
+		if (endpoints === void 0) return [];
+		const methods = group.actions.flatMap((action) => {
+			const endpoint = endpoints[action.name];
+			if (endpoint === void 0) return [];
+			const method = (input) => Effect.runPromise(endpoint({ payload: input ?? {} }));
+			return [[action.name, method]];
+		});
+		return [[group.name, Object.fromEntries(methods)]];
+	}));
+}
+//#endregion
+export { promise };