@gjermundgaraba/effect-actions 0.11.0 → 0.13.0

package/dist/ActionCli.d.mts

@@ -1,13 +1,32 @@
-import { BuiltIn } from "./internal/errors.mjs";
-import { ActionOf, BuildError, BuildServices, Holding, Known, Member, RequestOf, Selected, SelectedOf, Selection, Served } from "./internal/implementation.mjs";
-import { Action_d_exports, Any } from "./Action.mjs";
-import { VerifierError } from "./internal/authentication.mjs";
-import { Options, UserError } from "./internal/cli.mjs";
-import { AnyHttp, Options as Options$2 } from "./internal/client.mjs";
+import { BuiltIn } from "./contract/errors.mjs";
+import { ActionOf, BuildError, BuildServices, Holding, Known, Member, RequestOf, Selected, SelectedOf, Selection, Served } from "./contract/implementation.mjs";
+import { Action_d_exports, Any, Errors } from "./Action.mjs";
+import { VerifierError } from "./authentication/provider.mjs";
+import { Options, UserError } from "./cli/commands.mjs";
+import { AnyHttp, Options as Options$2 } from "./http/client.mjs";
 import { Effect, Schema } from "effect";
 import { HttpClient, HttpClientError } from "effect/http";
 import { Command } from "effect/cli";
-//#region src/ActionCli.d.ts
+//#region src/cli/ActionCli.d.ts
+interface AnyBinding {
+  readonly authentication?: {
+    readonly error: Errors;
+  } | undefined;
+  readonly actions: ReadonlyArray<Any>;
+  readonly error: Errors;
+}
+/**
+ * Make a command of your own fail as a derived command does. Give it what the command calls, the
+ * binding of `ActionHttp.client` or `ActionRpc.client`, or the actions of `Action.client`, and pipe the command's
+ * whole Effect through it: a failure that is a declared error, the binding's and its
+ * authentication's included, or a built-in one becomes a `UserError` whose message is its JSON, and any other, a transport
+ * failure for one, a `UserError` naming it and the causes beneath it. An Effect CLI error, your
+ * own `new CliError.UserError({ cause, userMessage })` included, passes through as it is. To
+ * add context, such as how far a batch got, print it before this in the pipe, with
+ * `Effect.tapError(() => Console.error(…))`: a `UserError` wrapped around the result would
+ * replace its JSON.
+ */
+export declare const toUserError: (calls: AnyBinding | ReadonlyArray<Any>) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, UserError<Exclude<E, import("effect/cli/CliError").CliError>> | Exclude<E, Exclude<E, import("effect/cli/CliError").CliError>>, R>;
 /**
  * An aggregate command of the actions `A`: its name, the actions that are its subcommands,
  * and their options.
@@ -25,33 +44,32 @@ interface Options$1<A extends Any = Any> {
    * `{ readFile: { positional: ["path"], render } }`.
    */
   readonly commands?: { readonly [K in A as K["name"]]?: Options<K>; };
+  /**
+   * Commands of your own beside the derived ones, as `Command.withSubcommands` takes them:
+   * `[importLinks]`, each made with Effect CLI's `Command.make`. One fails as you make it fail:
+   * with a `CliError.UserError` for `Command.run` to print its `userMessage` on stderr. Written
+   * in the call, or in options held with `satisfies` this type, the list adds its commands'
+   * failures and services to the aggregate's type; in options annotated with this type, it adds
+   * none.
+   */
+  readonly subcommands?: Subcommands | undefined;
 }
-/** The `commands` any member of `O` may give. */
+type Subcommands = ReadonlyArray<Command.Command.SubcommandEntry>;
+type OwnCommand<Own extends Subcommands> = Subcommands extends Own ? never : Own[number] extends (infer Entry) ? Entry extends Command.Command<infer _N, infer _I, infer _C, infer _E, infer _R> ? Entry : Entry extends Command.Command.SubcommandGroup<infer Commands> ? Commands[number] : never : never;
 type CommandsOf<O> = O extends unknown ? "commands" extends keyof O ? NonNullable<O["commands" & keyof O]> : never : never;
-/** The keys of any member of `C`. */
 type KeysOf<C> = C extends unknown ? keyof C : never;
-/** The options any member of `C` gives command `K`. */
 type CommandOf<C, K> = C extends unknown ? (K extends keyof C ? C[K] : never) : never;
-/**
- * No option, no command beyond the actions `A` of the target, and no command's option, beyond
- * `Keys`'s, in any member of `O`.
- */
 type KnownOptions<O, Keys, A extends Any> = Known<O, Keys> & ([CommandsOf<O>] extends [never] ? unknown : {
   readonly commands?: Known<CommandsOf<O>, { readonly [K in A["name"]]: Options<A>; }> & { readonly [K in KeysOf<CommandsOf<O>>]?: Known<CommandOf<CommandsOf<O>, K>, Options<Any>>; };
 });
-/** The implementation of `A` among `App`. */
 type Owning<App, A extends Any> = App extends unknown ? A extends ActionOf<App> ? App : never : never;
-/**
- * What one local command of `A` runs: its implementation's builder and authorization, then
- * its handler. Authorization may refuse and any handler fail with a built-in error, so
- * every one fails with `Action.BuiltIn` too.
- */
 type Local<App, A extends Any> = Effect.Effect<A["success"]["Type"], A["error"][number]["Type"] | BuildError<App, A> | BuiltIn, RequestOf<App, A> | BuildServices<App, A>>;
 /**
  * Project one implemented action into a native Effect CLI command that runs its handler in
  * process, behind its implementation's authorization. It is named after the action in kebab
  * case with one flag per field of its input (`--user-id`), or `--input` taking the whole input
- * as JSON when it is not a struct. It needs what the authorization, its handler and its builder
+ * as JSON when it is not a struct. The flag of an array of strings or numbers is repeated for each value, a boolean
+ * field is a switch, `--no-<name>` sending `false` as a required one left out does, and a field's `description` is its flag's help. It needs what the authorization, its handler and its builder
  * need; the host provides the identity. It prints the result on stdout; a failure is a
  * `UserError`, which `Command.run` prints on stderr. `remoteCommand` calls a server instead.
  */
@@ -75,24 +93,38 @@ export type RemoteCommandOptions<A extends Any = Any> = Options<A> & {
 export type RemoteOptions<A extends Any = Any> = Options$1<A> & {
   /**
    * Every subcommand's client options, as `ActionHttp.client` takes them: `baseUrl`, and
-   * `transformClient` for credentials. They reach this aggregate's requests alone.
+   * `transformClient` for credentials. They reach this aggregate's requests alone. A URL or a
+   * token read from `Config` goes instead into the `HttpClient` provided on the command, with
+   * `Command.provideEffect(HttpClient.HttpClient, …)`: it is read when a command runs, so
+   * `--help` needs neither, and a command of your own in `subcommands` calls through it too.
+   * A required one that is not set fails that Effect with a `ConfigError`, which is no
+   * command's failure and prints as a crash line: map the read,
+   * `Effect.mapError((cause) => new CliError.UserError({ cause, userMessage: "TOKEN is not set" }))`.
    */
   readonly client?: Options$2;
 };
-/** What an aggregate command over binding `H` fails with, running its actions `A`. */
 type HttpUserError<H extends AnyHttp, A extends Any> = UserError<A["error"][number]["Type"] | H["error"][number]["Type"] | VerifierError<A, H["authentication"]>["Type"] | BuiltIn | HttpClientError.HttpClientError | Schema.SchemaError>;
 /**
  * Project every implemented action as a subcommand of one aggregate command, each named after
  * its action in kebab case and run in process. `commands` gives a subcommand the options
- * `command` takes, by action name. `remote` calls a server instead.
+ * `command` takes, by action name; `subcommands` adds commands of your own, which
+ * `Command.withSubcommands` on the result would put in the derived ones' place. `remote` calls a
+ * server instead. A test runs it in memory, with no process:
+ * `Command.runWith(command, { version })(args)`.
+ * Guide: `docs/ActionCli.md` in this package; in an application: `examples/notes-service/src/commands.ts`.
  */
-export declare function make<const Apps extends Served, const O extends Selection<ActionOf<Member<Apps>>> = {}>(implementations: Apps, options: O & NoInfer<Options$1<ActionOf<Member<Apps>>>> & NoInfer<KnownOptions<O, Options$1, ActionOf<Member<Apps>>>>): Command.Command<string, {}, {}, UserError<Effect.Error<Local<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>>>, Effect.Services<Local<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>>>;
+export declare function make<const Apps extends Served, const O extends Selection<ActionOf<Member<Apps>>> = {}, const Own extends Subcommands = []>(implementations: Apps, options: O & NoInfer<Options$1<ActionOf<Member<Apps>>>> & NoInfer<KnownOptions<O, Options$1, ActionOf<Member<Apps>>>> & {
+  readonly subcommands?: Own | undefined;
+}): Command.Command<string, {}, {}, UserError<Effect.Error<Local<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>>> | Command.Error<OwnCommand<Own>>, Effect.Services<Local<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>> | Command.Services<OwnCommand<Own>>>;
 /**
  * Project every action of an HTTP binding as a subcommand of one aggregate command, derived as
- * `make` derives it, each calling its action over HTTP. `client` configures every
- * subcommand's client; `commands` gives a subcommand the options `command` takes.
+ * `make` derives it, each calling its action over HTTP. `client` configures every derived
+ * subcommand's client; `commands` gives one the options `command` takes; `subcommands` adds
+ * commands of your own.
  */
-export declare function remote<const H extends AnyHttp, const O extends Selection<H["actions"][number]> = {}>(binding: H, options: O & NoInfer<RemoteOptions<H["actions"][number]>> & NoInfer<KnownOptions<O, RemoteOptions<Any>, H["actions"][number]>>): Command.Command<string, {}, {}, HttpUserError<H, Selected<O, H["actions"][number]>>, HttpClient.HttpClient>;
+export declare function remote<const H extends AnyHttp, const O extends Selection<H["actions"][number]> = {}, const Own extends Subcommands = []>(binding: H, options: O & NoInfer<RemoteOptions<H["actions"][number]>> & NoInfer<KnownOptions<O, RemoteOptions<Any>, H["actions"][number]>> & {
+  readonly subcommands?: Own | undefined;
+}): Command.Command<string, {}, {}, HttpUserError<H, Selected<O, H["actions"][number]>> | Command.Error<OwnCommand<Own>>, HttpClient.HttpClient | Command.Services<OwnCommand<Own>>>;
 /**
  * A program whose stdout carries only its results, such as a CLI feeding scripts or an MCP
  * subprocess, applied last, before `NodeRuntime.runMain`: the default logger of every layer

package/dist/ActionCli.mjs

@@ -1,60 +1,60 @@
-import { assertDistinct, assertKnown } from "./internal/actions.mjs";
-import { Implementation, acquire, assertHeld, select, toList } from "./internal/implementation.mjs";
-import { assertInBinding, methods } from "./internal/client.mjs";
-import { command as command$1 } from "./internal/cli.mjs";
+import { assertDistinct, assertKnown } from "./contract/rules.mjs";
+import { Implementation, acquire, assertHeld, select, toList } from "./contract/implementation.mjs";
+import { withVerifierErrors } from "./authentication/provider.mjs";
+import { assertInBinding, methods } from "./http/client.mjs";
+import { command as command$1, failingAsDerived } from "./cli/commands.mjs";
 import { Cause, Effect, Logger, Runtime } from "effect";
 import { Command } from "effect/cli";
-//#region src/ActionCli.ts
+//#region src/cli/ActionCli.ts
 /**
-* Build the implementation's handlers for this call alone, run one action through its
-* authorization and handler, and release them: every local command, selected or aggregated.
-* The call's own scope, which every call has, closes first, so its finalizers run while the
-* builder's resources are still open; a local build never reuses one the host already made.
+* Make a command of your own fail as a derived command does. Give it what the command calls, the
+* binding of `ActionHttp.client` or `ActionRpc.client`, or the actions of `Action.client`, and pipe the command's
+* whole Effect through it: a failure that is a declared error, the binding's and its
+* authentication's included, or a built-in one becomes a `UserError` whose message is its JSON, and any other, a transport
+* failure for one, a `UserError` naming it and the causes beneath it. An Effect CLI error, your
+* own `new CliError.UserError({ cause, userMessage })` included, passes through as it is. To
+* add context, such as how far a batch got, print it before this in the pipe, with
+* `Effect.tapError(() => Console.error(…))`: a `UserError` wrapped around the result would
+* replace its JSON.
 */
-const local = (app, action, input) => {
-	const own = Implementation.share([action], app);
-	return Effect.flatMap(acquire([own]), (bound) => {
+const toUserError = (calls) => "actions" in calls ? failingAsDerived(calls.actions, (action) => endpointErrorsOf(calls, action)) : failingAsDerived(calls, () => []);
+const endpointErrorsOf = (binding, action) => withVerifierErrors(action, binding.error, binding.authentication?.error);
+const runWithBuildOfItsOwn = (app, action, input) => {
+	const thisActionOnly = Implementation.share([action], app);
+	return Effect.flatMap(acquire([thisActionOnly]), (bound) => {
 		const [, run] = bound.find(([candidate]) => candidate === action) ?? [];
 		return run === void 0 ? Effect.die(/* @__PURE__ */ new Error(`No handler for ${action.name}`)) : run(input);
-	}).pipe(Effect.provide(Implementation.layerOf(own), { local: true }));
+	}).pipe(Effect.provide(Implementation.layerOf(thisActionOnly), { local: true }));
 };
-/**
-* The one implementation of `action` among `apps`. One implemented twice is refused rather
-* than the first run; other actions' names are not this command's to check.
-*/
-const implementationOf = (apps, action) => {
+const theImplementationOf = (apps, action) => {
 	const [app, ...others] = apps.filter((candidate) => candidate.actions.includes(action));
 	if (app === void 0) throw new Error(`Action "${action.name}" has no implementation here`);
 	if (others.length > 0) throw new Error(`Action "${action.name}" is implemented twice here`);
 	return app;
 };
-/** One command running `action` in process, by its one implementation among `apps`. */
 const inProcess = (apps, action, options) => {
-	const app = implementationOf(apps, action);
-	return command$1(action, (input) => local(app, action, input), options);
+	const app = theImplementationOf(apps, action);
+	return command$1(action, (input) => runWithBuildOfItsOwn(app, action, input), options);
 };
-/**
-* One command calling `action` through the binding's client, made with `client` on the
-* host's `HttpClient`, whose failures include the binding's errors.
-*/
 const overHttp = (binding, action, options, client) => {
 	assertInBinding(binding.actions, action);
-	return command$1(action, (input) => Effect.flatMap(methods(binding, client), (methodOf) => methodOf(action)(input)), options, binding.error);
+	return command$1(action, (input) => Effect.flatMap(methods(binding, client), (methodOf) => methodOf(action)(input)), options, endpointErrorsOf(binding, action));
 };
-/**
-* One aggregate command named `name`, a subcommand per action of `actions`, each made by
-* `project` with its options in `commands`: a local aggregate's and a remote one's.
-*/
-const aggregate = (name, actions, commands, project) => {
-	const subcommands = actions.map((action) => ({
-		action,
+const aggregateCommand = (name, actions, commands, own, project) => {
+	const derived = actions.map((action) => ({
+		claimant: `action ${action.name}`,
 		command: project(action, Object.hasOwn(commands, action.name) ? commands[action.name] : void 0)
 	}));
-	assertDistinct("command", subcommands, ({ command }) => command.name, ({ action }) => `action ${action.name}`);
-	return Command.make(name).pipe(Command.withSubcommands(subcommands.map(({ command }) => command)));
+	assertDistinct("command", [...derived.map(({ claimant, command }) => ({
+		claimant,
+		name: command.name
+	})), ...own.flatMap((entry) => Command.isCommand(entry) ? [entry] : entry.commands).map((command) => ({
+		claimant: "subcommands",
+		name: command.name
+	}))], ({ name: claimed }) => claimed, ({ claimant }) => claimant);
+	return Command.make(name).pipe(Command.withSubcommands([...derived.map(({ command }) => command), ...own]));
 };
-/** A command of any action of the target, so one record serves several selections. */
-const commandsOf = (commands, actions) => {
+const checkedCommandsOf = (commands, actions) => {
 	const given = commands ?? {};
 	assertKnown("commands", Object.keys(given), actions.map((action) => action.name));
 	return given;
@@ -63,7 +63,8 @@ const commandsOf = (commands, actions) => {
 * Project one implemented action into a native Effect CLI command that runs its handler in
 * process, behind its implementation's authorization. It is named after the action in kebab
 * case with one flag per field of its input (`--user-id`), or `--input` taking the whole input
-* as JSON when it is not a struct. It needs what the authorization, its handler and its builder
+* as JSON when it is not a struct. The flag of an array of strings or numbers is repeated for each value, a boolean
+* field is a switch, `--no-<name>` sending `false` as a required one left out does, and a field's `description` is its flag's help. It needs what the authorization, its handler and its builder
 * need; the host provides the identity. It prints the result on stdout; a failure is a
 * `UserError`, which `Command.run` prints on stderr. `remoteCommand` calls a server instead.
 */
@@ -83,24 +84,29 @@ function remoteCommand(binding, action, options) {
 /**
 * Project every implemented action as a subcommand of one aggregate command, each named after
 * its action in kebab case and run in process. `commands` gives a subcommand the options
-* `command` takes, by action name. `remote` calls a server instead.
+* `command` takes, by action name; `subcommands` adds commands of your own, which
+* `Command.withSubcommands` on the result would put in the derived ones' place. `remote` calls a
+* server instead. A test runs it in memory, with no process:
+* `Command.runWith(command, { version })(args)`.
+* Guide: `docs/ActionCli.md` in this package; in an application: `examples/notes-service/src/commands.ts`.
 */
 function make(implementations, options) {
 	const apps = toList(implementations);
-	const commands = commandsOf(options.commands, apps.flatMap((app) => app.actions));
+	const commands = checkedCommandsOf(options.commands, apps.flatMap((app) => app.actions));
 	const served = select(apps, options.actions);
-	return aggregate(options.name, served.flatMap((app) => app.actions), commands, (action, syntax) => inProcess(served, action, syntax));
+	return aggregateCommand(options.name, served.flatMap((app) => app.actions), commands, options.subcommands ?? [], (action, syntax) => inProcess(served, action, syntax));
 }
 /**
 * Project every action of an HTTP binding as a subcommand of one aggregate command, derived as
-* `make` derives it, each calling its action over HTTP. `client` configures every
-* subcommand's client; `commands` gives a subcommand the options `command` takes.
+* `make` derives it, each calling its action over HTTP. `client` configures every derived
+* subcommand's client; `commands` gives one the options `command` takes; `subcommands` adds
+* commands of your own.
 */
 function remote(binding, options) {
 	const listed = options.actions;
 	if (listed !== void 0) assertHeld("the binding does not hold it", listed, binding.actions);
-	const commands = commandsOf(options.commands, binding.actions);
-	return aggregate(options.name, binding.actions.filter((action) => listed?.includes(action) ?? true), commands, (action, syntax) => overHttp(binding, action, syntax, options.client));
+	const commands = checkedCommandsOf(options.commands, binding.actions);
+	return aggregateCommand(options.name, binding.actions.filter((action) => listed?.includes(action) ?? true), commands, options.subcommands ?? [], (action, syntax) => overHttp(binding, action, syntax, options.client));
 }
 /**
 * A program whose stdout carries only its results, such as a CLI feeding scripts or an MCP
@@ -114,11 +120,11 @@ function remote(binding, options) {
 const logToStderr = (self) => self.pipe(Effect.catchCause((cause) => {
 	if (Cause.hasInterruptsOnly(cause)) return Effect.interrupt;
 	const squashed = Cause.squash(cause);
-	const reported = Object.assign(new Error("Reported on stderr", { cause }), {
+	const reportedDefectKeepingCause = Object.assign(new Error("Reported on stderr", { cause }), {
 		[Runtime.errorReported]: false,
 		[Runtime.errorExitCode]: Runtime.getErrorExitCode(squashed)
 	});
-	return Effect.andThen(Runtime.getErrorReported(squashed) ? Effect.logError(cause) : Effect.void, Effect.die(reported));
+	return Effect.andThen(Runtime.getErrorReported(squashed) ? Effect.logError(cause) : Effect.void, Effect.die(reportedDefectKeepingCause));
 }), Effect.provideService(Logger.LogToStderr, true));
 //#endregion
-export { command, logToStderr, make, remote, remoteCommand };
+export { command, logToStderr, make, remote, remoteCommand, toUserError };

package/dist/ActionHttp.d.mts

@@ -1,14 +1,13 @@
-import { Anyone } from "./internal/actions.mjs";
-import { BuiltIn, BuiltIns } from "./internal/errors.mjs";
-import { BuildError, BuildServices, Holding, Known, Member, Protected, Selected, Served, Serving } from "./internal/implementation.mjs";
+import { Anyone, Certain, ErrorsOf } from "./contract/rules.mjs";
+import { BuiltIn, BuiltIns } from "./contract/errors.mjs";
+import { BuildError, Holding, Known, Member, MiddlewareOf, Protected, Selected, Served, Serving } from "./contract/implementation.mjs";
 import { Action_d_exports, Any, Errors } from "./Action.mjs";
-import { Any as Any$1, Identity, Matching, RemoteRequest, Required, ServedProvider, VerifierError } from "./internal/authentication.mjs";
-import { AnyHttp, Client, MethodError, Options } from "./internal/client.mjs";
-import { ErrorsOf } from "./internal/declared.mjs";
+import { Any as Any$1, DescriptorOf, Identity, Matching, PublicOnly, RemoteRequest, Required, ServedProvider, ServerBuildServices, VerifierError } from "./authentication/provider.mjs";
+import { AnyHttp, Client, MethodError, Options } from "./http/client.mjs";
 import { Context, Effect, FileSystem, Layer, Path, Schema, Types } from "effect";
 import { Etag, HttpClient, HttpPlatform, HttpRouter } from "effect/http";
 import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware } from "effect/http-api";
-//#region src/ActionHttp.d.ts
+//#region src/http/ActionHttp.d.ts
 /** What `fetchClient` takes: `client`'s options, and the `fetch` its calls send with. */
 export interface FetchClientOptions extends Options {
   /**
@@ -17,49 +16,13 @@ export interface FetchClientOptions extends Options {
    */
   readonly fetch?: typeof globalThis.fetch | undefined;
 }
-/** Native endpoint middleware, as `HttpApiMiddleware.Service` declares it. */
 type Middleware = ReadonlyArray<Context.Key<HttpApiMiddleware.AnyId, unknown>>;
-/** The identifier a middleware's service key declares. */
 type IdOf<K> = K extends Context.Key<infer I extends HttpApiMiddleware.AnyId, unknown> ? I : never;
-/**
- * What the request owes past the middleware `M`, the first innermost, around what `R` owes:
- * each removes what it provides and adds what it requires, as native endpoints apply them.
- * An array of unknown length, which may hold none of them, provides nothing and owes what
- * any of them requires; so does a slot that may hold one of several, as only one runs.
- */
 type Through<M extends Middleware, R> = number extends M["length"] ? R | HttpApiMiddleware.Requires<IdOf<M[number]>> : M extends readonly [infer K, ...infer Rest extends Middleware] ? Through<Rest, true extends Types.IsUnion<IdOf<K>> ? R | HttpApiMiddleware.Requires<IdOf<K>> : HttpApiMiddleware.ApplyServices<IdOf<K>, R>> : R;
-/**
- * The middleware options `O` install: its `middleware` when always given, an array of unknown
- * length when it may be absent, which installs none or all of them, and none otherwise.
- */
-type MiddlewareOf<O> = O extends {
-  readonly middleware: infer M extends Middleware;
-} ? M : O extends {
-  readonly middleware?: infer M extends Middleware | undefined;
-} ? "middleware" extends keyof O ? ReadonlyArray<NonNullable<M>[number]> : [] : [];
-/**
- * The layer's middleware, refused when one fails with an error neither the binding, `E`, nor
- * every endpoint declares, or needs a client counterpart: neither reaches the binding's
- * clients, which decode only what the binding and the built-ins declare. A failure an
- * action's callers see after decoding is its handler's, declared on the contract and decoded
- * by every client.
- */
 type ServerOnly<M extends Middleware, E extends Errors> = [Exclude<HttpApiMiddleware.Error<IdOf<M[number]>>, Extract<Certain<E>, Errors[number]>["Type"] | BuiltIn> | HttpApiMiddleware.MiddlewareClient<IdOf<M[number]>>] extends [never] ? unknown : {
   readonly "Layer middleware fails only with the binding's errors and needs no client": never;
 };
-/** `T` where it is one type, not a union: what a list's slot of type `T` surely holds. */
-type Single<T> = true extends Types.IsUnion<T> ? never : T;
-/**
- * The errors a binding of errors `E` surely declares: each slot of one error in a list of
- * fixed length, never one of an array of unknown length, which may be empty, nor of a list
- * `E` may be one of several.
- */
-type Certain<E extends Errors> = true extends Types.IsUnion<E> ? never : number extends E["length"] ? never : { readonly [K in keyof E]: Single<E[K]>; }[number];
-/**
- * The layer serving the actions `A` of `Apps` through the binding `H`, behind the middleware
- * `M`: an implementation holding none of them is not built.
- */
-type HttpLayer<H extends AnyHttp, Apps extends Served, M extends Middleware, A extends Any = H["actions"][number]> = Layer.Layer<never, BuildError<Holding<Member<Apps>, A>, A>, BuildServices<Holding<Member<Apps>, A>, A> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", LayerRequest<Member<Apps>, A, M>> | ServedProvider<Member<Apps>, A, H extends {
+type HttpLayer<H extends AnyHttp, Apps extends Served, M extends Middleware, A extends Any = H["actions"][number]> = Layer.Layer<never, BuildError<Holding<Member<Apps>, A>, A>, ServerBuildServices<Holding<Member<Apps>, A>, A> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", LayerRequest<Member<Apps>, A, M>> | ServedProvider<Member<Apps>, A, H extends {
   readonly authentication: infer D;
 } ? D : never> | IdOf<M[number]> | Etag.Generator | FileSystem.FileSystem | HttpPlatform.HttpPlatform | Path.Path>;
 /** `ActionHttp.layer`'s options. */
@@ -77,20 +40,9 @@ export interface LayerOptions<M extends Middleware = [], A extends Any = never>
    */
   readonly middleware?: M;
 }
-/** What the layer serving `A` of `App` behind middleware `M` owes per request. */
 type LayerRequest<App, A extends Any, M extends Middleware> = Exclude<Through<M, RemoteRequest<App, A>>, HttpRouter.Provided | ([Extract<Serving<App, A>, {
   readonly caller: typeof Anyone;
 }>] extends [never] ? Identity<Protected<Serving<App, A>>> : never)>;
-/** Actions a binding takes without options: public ones, as a protected one names its descriptor. */
-type PublicOnly<Actions extends ReadonlyArray<Any>> = [Exclude<Actions[number], {
-  readonly caller: typeof Anyone;
-}>] extends [never] ? unknown : {
-  readonly "Protected actions take options naming their authentication": never;
-};
-/** The descriptor options `O` name, where they always name one. */
-type DescriptorOf<O> = [O] extends [{
-  readonly authentication: infer D extends Any$1;
-}] ? D : undefined;
 /** Contract-level configuration shared by servers and clients. */
 interface Options$1<E extends Errors = Errors> {
   readonly prefix?: `/${string}`;
@@ -99,11 +51,6 @@ interface Options$1<E extends Errors = Errors> {
   readonly authentication?: Any$1;
 }
 type Endpoint<A extends Any, E extends Errors, D> = A extends Any ? HttpApiEndpoint.HttpApiEndpoint<A["name"], "POST", `/${string}`, never, never, Schema.toCodecJson<A["input"]>, never, Schema.toCodecJson<A["success"]>, Schema.toCodecJson<A["error"][number] | E[number] | VerifierError<A, D> | BuiltIns>, never> : never;
-/**
- * The native `HttpApi` of `Actions`: one top-level group, so native client methods are
- * not nested, named after the binding's mount path, `/` at the root, so bindings composed
- * into one host API keep their own groups.
- */
 type Api<Actions extends ReadonlyArray<Any>, E extends Errors, D> = HttpApi.HttpApi<"actions", HttpApiGroup.HttpApiGroup<string, Endpoint<Actions[number], E, D>, true>>;
 /**
  * An HTTP binding: actions, the errors every endpoint declares, and where they are mounted.
@@ -122,11 +69,12 @@ export interface Binding<Actions extends ReadonlyArray<Any>, E extends Errors =
 }
 /**
  * Bind actions once, for servers and clients alike, each at `POST <prefix>/<action>`.
- * Every endpoint declares its action's errors, the binding's `errors`, and the built-in
+ * Every endpoint declares its action's errors, the binding's `error`, and the built-in
  * `InvalidInput`, `Unauthenticated` and `Forbidden`, so clients decode each as a typed
  * failure. A union's own `httpApiStatus` applies to every member; otherwise, each member
  * uses its own status, or 422 without one. Protected contracts receive native endpoint
  * security middleware: the same descriptor documents their credentials and enforces them.
+ * Guide: `docs/ActionHttp.md` in this package; in an application: `examples/notes-service/src/routes.ts`.
  */
 export declare function make<const Actions extends ReadonlyArray<Any & {
   readonly caller: typeof Anyone;
@@ -149,22 +97,25 @@ export declare function make<const Actions extends ReadonlyArray<Any>>(actions:
  * need, until its `middleware` or middleware provided around it provides them, the identity
  * of a protected action excepted, which its authentication provides; the router provides
  * its own, such as the request, to every route. Its routes take only requests typed as JSON,
- * and what middleware provides per request wins over what the layer was built with.
+ * and what middleware provides per request wins over what the layer was built with. A request
+ * body is read whole, however large, unless the host limits it where the routes are served:
+ * `Layer.provide(Layer.succeed(HttpServerRequest.MaxBodySize, ByteSize.mebibytes(1)))`.
  */
 export declare function layer<const H extends AnyHttp, const Apps extends Served>(binding: H, implementations: Apps): HttpLayer<H, Apps, []>;
-export declare function layer<const H extends AnyHttp, const Apps extends Served, const O extends LayerOptions<Middleware, H["actions"][number]>>(binding: H, implementations: Apps, options: O & ServerOnly<MiddlewareOf<O>, H["error"]> & NoInfer<Known<O, LayerOptions<Middleware>>>): HttpLayer<H, Apps, MiddlewareOf<O>, Selected<O, H["actions"][number]>>;
+export declare function layer<const H extends AnyHttp, const Apps extends Served, const O extends LayerOptions<Middleware, H["actions"][number]>>(binding: H, implementations: Apps, options: O & ServerOnly<MiddlewareOf<O, Middleware>, H["error"]> & NoInfer<Known<O, LayerOptions<Middleware>>>): HttpLayer<H, Apps, MiddlewareOf<O, Middleware>, Selected<O, H["actions"][number]>>;
 /**
  * Effect's native `HttpApiClient` for a binding, one method per action taking the
  * action's input directly: `client.greet({ name })`. The argument may be omitted when `{}`
  * is a valid input. Requires the native `HttpClient`, as `HttpApiClient.make` does.
- * The options are the native ones, `baseUrl` and `transformClient`. The native client
- * itself stays available: `HttpApiClient.make(Http.api)`.
+ * The options are the native ones, `baseUrl` and `transformClient`, a bearer token being
+ * `transformClient: HttpClient.mapRequest(HttpClientRequest.bearerToken(token))`. The native
+ * client itself stays available: `HttpApiClient.make(Http.api)`.
  *
  * A call fails with a declared error value (the action's own, or a built-in
  * `InvalidInput`, `Unauthenticated` or `Forbidden`), 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.
+ * declare, or a `SchemaError` when the success does not decode. An input that does not encode
+ * fails with `InvalidInput`, and nothing is sent.
  */
 export declare function client<const H extends AnyHttp>(binding: H, options?: Options): Effect.Effect<Client<H>, never, HttpClient.HttpClient>;
 /**

package/dist/ActionHttp.mjs

@@ -1,61 +1,27 @@
-import { Anyone, assertDistinct, assertOnce, assertOwnTags, errorList, projectedErrors } from "./internal/actions.mjs";
-import { acquire, assertHeld, provideHandlers, select, toList } from "./internal/implementation.mjs";
-import { assertAuthentication } from "./internal/authentication.mjs";
-import { declared } from "./internal/declared.mjs";
-import { methods } from "./internal/client.mjs";
-import { SchemaErrors, schemaErrors } from "./internal/schema-errors.mjs";
+import { Anyone, assertDistinct, assertOnce, assertOwnTags, errorList, projectedErrors } from "./contract/rules.mjs";
+import { acquire, provideHandlers, servedBy, toList } from "./contract/implementation.mjs";
+import { assertAuthentication, providerOf, withVerifierErrors } from "./authentication/provider.mjs";
+import { declared } from "./http/declared.mjs";
+import { methods } from "./http/client.mjs";
+import { SchemaErrors, schemaErrors } from "./http/schema-errors.mjs";
 import { Context, Effect, Layer, Scope } from "effect";
 import { FetchHttpClient, HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/http";
 import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, HttpApiSchema, OpenApi } from "effect/http-api";
-//#region src/ActionHttp.ts
-/** The mount path's segments: `api` by default; none for `/`. */
+//#region src/http/ActionHttp.ts
 const mountSegments = (prefix) => (prefix ?? "/api").split("/").filter((segment) => segment !== "");
-/** An absolute route from path segments. */
-const route = (segments) => `/${segments.join("/")}`;
-/**
-* The name of a binding's one native group: its OpenAPI tag, by which the native `addHttpApi`
-* keys groups. It is the mount path, `/` at the root, which no segment contains.
-*/
+const absolutePath = (segments) => `/${segments.join("/")}`;
 const groupName = (mount) => mount.join("/") || "/";
-/** A native API of one top-level group of `endpoints`. */
 const apiOf = (group, endpoints) => {
 	const empty = HttpApiGroup.make(group, { topLevel: true });
 	const [first, ...rest] = endpoints;
 	return HttpApi.make("actions").annotate(HttpApi.ParseOptions, { errors: "all" }).add(first === void 0 ? empty : empty.add(first, ...rest));
 };
-/**
-* `apps` narrowed to the actions the layer serves, matched by identity: those `listed`, which
-* the binding must hold, or every one of the binding's they hold, each once. An
-* implementation holding none of them is left out, and not built. Implementations holding
-* none of the binding's actions are refused, as the wrong implementations or the wrong
-* binding; a name the binding holds is marked as another contract's, as a second copy of the
-* contracts module makes one.
-*/
-const servedBy = (binding, apps, listed) => {
-	if (listed !== void 0) assertHeld("the binding does not hold it", listed, binding.actions);
-	const held = apps.flatMap((app) => app.actions);
-	const served = select(apps, listed ?? binding.actions.filter((action) => held.includes(action)));
-	const actions = served.flatMap((app) => app.actions);
-	if (actions.length === 0 && listed === void 0 && apps.length > 0) {
-		const bound = new Set(binding.actions.map(({ name }) => name));
-		throw new Error(`No action of these implementations is in this HTTP binding: ${held.map(({ name }) => bound.has(name) ? `${name} (another contract)` : name).join(", ") || "none"}`);
-	}
-	assertOnce("served action", actions);
-	return served;
-};
-/**
-* The native endpoint of `action` at `path`, declaring its action's errors, the binding's
-* `errors` and the built-in ones: what `make` documents and `layer` serves. Its payload is
-* JSON whatever encoding the input is annotated with, which no other surface reads either:
-* `HttpApi` would take a form or text body for it, which a page sends without a preflight.
-*/
 const endpointOf = (action, path, errors) => HttpApiEndpoint.post(action.name, path, {
 	payload: action.input.pipe(HttpApiSchema.asJson()),
 	success: action.success,
 	error: projectedErrors(action, errors).flatMap(declared)
 });
-/** An endpoint wrapped in a layer's middleware, the first innermost. */
-const within = (endpoint, middleware = []) => middleware.reduce((inner, key) => inner.middleware(key), endpoint);
+const withinLayerMiddleware = (endpoint, middleware = []) => middleware.reduce((inner, key) => inner.middleware(key), endpoint);
 function make(actions, options = {}) {
 	assertOnce("action", actions);
 	const errors = errorList(options.error);
@@ -63,52 +29,37 @@ function make(actions, options = {}) {
 	assertAuthentication(actions, options.authentication);
 	const mount = mountSegments(options.prefix);
 	const security = options.authentication?.["~middleware"];
-	const verifierErrors = options.authentication?.error ?? [];
 	const endpoints = actions.map((action) => {
 		const isPublic = security === void 0 || action.caller === Anyone;
-		const endpoint = endpointOf(action, route([...mount, action.name]), isPublic ? errors : [...errors, ...verifierErrors]).annotate(OpenApi.Description, action.description);
+		const endpoint = endpointOf(action, absolutePath([...mount, action.name]), withVerifierErrors(action, errors, options.authentication?.error)).annotate(OpenApi.Description, action.description);
 		return isPublic ? endpoint : endpoint.middleware(security);
 	});
 	const api = apiOf(groupName(mount), endpoints);
 	return {
 		actions,
 		error: errors,
-		prefix: route(mount),
+		prefix: absolutePath(mount),
 		api,
 		authentication: options.authentication
 	};
 }
-/**
-* `group`, built in an empty context rather than the one around it: `HttpApiBuilder` lays
-* the context a group is built in over every request's, where a startup value would replace
-* what middleware provides for the request. `entry` puts that context beneath it instead.
-*/
-const buildAlone = (group) => Layer.fromBuild((memoMap, scope) => Effect.setContext(Layer.buildWithMemoMap(group, memoMap, scope), Context.empty()));
-/**
-* Restore startup dependencies beneath request context, so a caller's services win.
-*/
-const entry = () => HttpRouter.middleware(Effect.map(Effect.context(), (built) => {
+const buildInEmptyContext = (group) => Layer.fromBuild((memoMap, scope) => Effect.setContext(Layer.buildWithMemoMap(group, memoMap, scope), Context.empty()));
+const startupBeneathRequest = () => HttpRouter.middleware(Effect.map(Effect.context(), (built) => {
 	const startup = Context.omit(Scope.Scope)(built);
 	return (route) => Effect.updateContext(route, (current) => Context.merge(startup, current));
 })).layer;
-/**
-* Answers a protected route's step-up refusal, as it leaves the layer's middleware, with its
-* challenge: the provider's `stepUp`, inside the authentication.
-*/
 var StepUp = class extends HttpApiMiddleware.Service()("effect-actions/ActionHttp/StepUp") {};
-/** Require JSON media typing after endpoint authentication, before payload decoding. */
 var JsonContentType = class extends HttpApiMiddleware.Service()("effect-actions/ActionHttp/JsonContentType") {};
-/** `JsonContentType`'s server side, built by `layer` alone, so a client's bundle leaves it out. */
 const jsonContentType = () => Layer.succeed(JsonContentType, (route) => Effect.flatMap(HttpServerRequest.HttpServerRequest, (request) => request.headers["content-type"] === void 0 ? Effect.succeed(HttpServerResponse.text("Unsupported content-type: none", { status: 415 })) : route));
 function layer(binding, served, options = {}) {
-	const apps = servedBy(binding, toList(served), options.actions);
+	const apps = servedBy("HTTP binding", binding.actions, toList(served), options.actions);
 	const actions = apps.flatMap((app) => app.actions);
 	assertAuthentication(actions, binding.authentication);
 	assertDistinct("middleware", options.middleware ?? [], (key) => key.key);
 	const mount = mountSegments(binding.prefix);
 	const name = groupName(mount);
 	const api = apiOf(name, actions.map((action) => {
-		const endpoint = within(endpointOf(action, route([...mount, action.name]), binding.error).middleware(JsonContentType).middleware(SchemaErrors), options.middleware);
+		const endpoint = withinLayerMiddleware(endpointOf(action, absolutePath([...mount, action.name]), binding.error).middleware(JsonContentType).middleware(SchemaErrors), options.middleware);
 		return action.caller === Anyone || binding.authentication === void 0 ? endpoint : endpoint.middleware(StepUp).middleware(binding.authentication["~middleware"]);
 	})).annotate(HttpApi.PayloadParseOptions, {
 		errors: "all",
@@ -117,19 +68,18 @@ function layer(binding, served, options = {}) {
 	const handlers = Layer.unwrap(Effect.gen(function* () {
 		const bound = yield* acquire(apps);
 		const auth = actions.some((action) => action.caller !== Anyone) ? binding.authentication : void 0;
-		const authentication = auth === void 0 ? Layer.empty : yield* Effect.flatMap(auth["~provider"], (provider) => provider.descriptor === auth ? Effect.succeed(Layer.mergeAll(Layer.succeed(auth["~middleware"], provider.middleware), Layer.succeed(StepUp, provider.stepUp))) : Effect.die(/* @__PURE__ */ new Error(`Authentication "${auth.name}": the binding's descriptor is not its provider's; build both from one descriptor`)));
-		const middleware = yield* Effect.forEach(options.middleware ?? [], (key) => Effect.map(Effect.service(key), (service) => Layer.succeed(key, service)));
+		const authentication = auth === void 0 ? Layer.empty : yield* Effect.map(providerOf(auth), (provider) => Layer.mergeAll(Layer.succeed(auth["~middleware"], provider.middleware), Layer.succeed(StepUp, provider.stepUp)));
+		const hostProvidedMiddleware = yield* Effect.forEach(options.middleware ?? [], (key) => Effect.map(Effect.service(key), (service) => Layer.succeed(key, service)));
 		const byName = Object.fromEntries(bound.map(([action, run]) => [action.name, (request) => run(request.payload)]));
 		return HttpApiBuilder.group(api, name, (builder) => builder.handleAll(byName)).pipe(Layer.provide([
 			schemaErrors(),
 			jsonContentType(),
 			authentication,
-			...middleware
-		]), buildAlone);
+			...hostProvidedMiddleware
+		]), buildInEmptyContext);
 	})).pipe(provideHandlers(apps));
-	return HttpApiBuilder.layer(api).pipe(Layer.provide(handlers), Layer.provide(entry()));
+	return HttpApiBuilder.layer(api).pipe(Layer.provide(handlers), Layer.provide(startupBeneathRequest()));
 }
-/** A binding's client, erased: `client` and `fetchClient` restore its exact type. */
 const erasedClient = (binding, options) => Effect.map(methods(binding, options), (methodOf) => Object.fromEntries(binding.actions.map((action) => [action.name, methodOf(action)])));
 function client(binding, options) {
 	return erasedClient(binding, options);