@gjermundgaraba/effect-actions 0.8.0 → 0.10.0

package/dist/internal/actions.d.mts

@@ -1,29 +1,9 @@
-import { Action_d_exports, Any, Codec } from "../Action.mjs";
-import { HttpApiError } from "effect/http-api";
+import "../Action.mjs";
+import { SchemaAST } from "effect";
 //#region src/internal/actions.d.ts
-/** One side of a schema-error policy: the error it answers with, and how to make it. */
-export interface SchemaErrorAnswer<E extends Codec> {
-  /** A declared error schema; its `httpApiStatus` is the HTTP status of the answer. */
-  readonly schema: E;
-  readonly make: (failure: HttpApiError.HttpApiSchemaError) => NoInfer<E["Type"]>;
-}
 /**
- * Pure HTTP policy for native schema failures, split by whose fault they are. The
- * library owns the split, so every group draws it the same way.
+ * The caller of a public action: anyone, signed in or not. Registered globally, so two copies
+ * of the package agree on it, as they agree on a name.
  */
-export interface SchemaErrorPolicy<Invalid extends Codec = Codec, Internal extends Codec = Codec> {
-  /** The request did not decode: its payload, or its params, headers or query. */
-  readonly invalid: SchemaErrorAnswer<Invalid>;
-  /** The handler's result did not encode: its body or its response headers. */
-  readonly internal: SchemaErrorAnswer<Internal>;
-}
-/** The contract half of a group: what adapters and clients need, without `implement`. */
-export interface Actions<Name extends string = string, A extends ReadonlyArray<Any> = ReadonlyArray<Any>, PolicyError extends Codec = Codec> {
-  readonly name: Name;
-  readonly actions: A;
-  /** How HTTP answers failed decoding or encoding; native behavior without one. MCP is unaffected. */
-  readonly schemaError: SchemaErrorPolicy<PolicyError, PolicyError> | undefined;
-}
-/** The errors a group's policy may answer with, by lookup rather than a conditional type. */
-export type PolicyError<G extends Actions> = NonNullable<G["schemaError"]>[keyof SchemaErrorPolicy]["schema"];
+export declare const Anyone: unique symbol;
 //#endregion

package/dist/internal/actions.mjs

@@ -1,41 +1,89 @@
+import { builtIns, statuses } from "./errors.mjs";
+import { Predicate, Schema, SchemaAST } from "effect";
 //#region src/internal/actions.ts
-/** Each distinct error a policy may answer with, invalid first. */
-const policyErrors = (policy) => [.../* @__PURE__ */ new Set([policy.invalid.schema, policy.internal.schema])];
 /**
-* `HttpApiBuilder` reports these kinds while encoding the handler's answer, after the
-* handler ran; every other kind (`Payload`, `Params`, `Headers`, `Query`) comes from
-* decoding the request before it.
+* The list an `error` option stands for: one schema, a list as given, or none, as
+* `HttpApiEndpoint` takes it.
 */
-const responseKinds = /* @__PURE__ */ new Set(["Body", "ResponseHeaders"]);
-/** The policy's answer to one native failure: `internal` for the response side, else `invalid`. */
-const answerSchemaError = (policy, failure) => responseKinds.has(failure.kind) ? policy.internal.make(failure) : policy.invalid.make(failure);
+const errorList = (error) => error === void 0 ? [] : Schema.isSchema(error) ? [error] : error;
 /**
-* An action's own failures plus the ones its surface answers with, which is what
-* a projection of that action declares. A schema the action already declares is
-* not repeated.
+* What a projection of an action declares: the built-in errors, the action's own, and any
+* its surface adds, such as a binding's. The built-ins come first, since a failure encodes
+* and decodes with the first schema that accepts it, and they are classes, which accept
+* only their own instances: a loose schema of the action's never captures one. A schema
+* listed twice is not repeated.
 */
-const projectedErrors = (action, surface) => [.../* @__PURE__ */ new Set([...action.errors, ...surface ?? []])];
-const validName = /^[A-Za-z0-9_-]+$/;
+const projectedErrors = (action, surface = []) => [.../* @__PURE__ */ new Set([
+	...builtIns,
+	...action.error,
+	...surface
+])];
+/**
+* The caller of a public action: anyone, signed in or not. Registered globally, so two copies
+* of the package agree on it, as they agree on a name.
+*/
+const Anyone = Symbol.for("@gjermundgaraba/effect-actions/Anyone");
+const validName = /^[A-Za-z0-9_-]{1,128}$/;
 /** Names become path segments, OpenAPI identifiers and client method keys. */
 const assertName = (what, name) => {
 	if (!validName.test(name) || name === "then") throw new Error(`Invalid ${what}: ${name}`);
 };
 /**
-* The one item of `items` named `name`, narrowed to that contract. A caller passes
-* a literal name, so a miss is a programming error reported as `Unknown <what>`.
+* Names are checked by whoever owns them: an implementation, a binding, a CLI, or the MCP
+* tools. `claimantOf` says who claims a name, so a clash between two claimants names both.
 */
-const selectNamed = (items, name, what) => {
-	const item = items.find((candidate) => candidate.name === name);
-	if (item === void 0) throw new Error(`Unknown ${what}`);
-	return item;
-};
-/** Each namespace is checked by whoever owns it: a group, the routes, or the MCP tools. */
-const assertDistinct = (what, names) => {
-	const seen = /* @__PURE__ */ new Set();
-	for (const name of names) {
-		if (seen.has(name)) throw new Error(`Duplicate ${what}: ${name}`);
-		seen.add(name);
+const assertDistinct = (what, items, nameOf, claimantOf = nameOf) => {
+	const seen = /* @__PURE__ */ new Map();
+	for (const item of items) {
+		const name = nameOf(item);
+		const claimant = claimantOf(item);
+		const other = seen.get(name);
+		if (other !== void 0) {
+			const by = other === claimant ? "" : `, claimed by ${other} and ${claimant}`;
+			throw new Error(`Duplicate ${what}: ${name}${by}`);
+		}
+		seen.set(name, claimant);
 	}
 };
+/** Refuse an action name `actions` hold twice. */
+const assertOnce = (what, actions) => assertDistinct(what, actions, (action) => action.name);
+/**
+* Refuse a key of options keyed by action name, such as handlers, tools or commands, that no
+* action of `names` has, so a stale option cannot outlive its action.
+*/
+const assertKnown = (what, keys, names) => {
+	const unknown = keys.filter((key) => !names.includes(key));
+	if (unknown.length > 0) throw new Error(`Unknown ${what}: ${unknown.join(", ")}`);
+};
+/** `ast` with any suspension at its top resolved, as a recursive schema's is. */
+const unsuspended = (ast) => SchemaAST.isSuspend(ast) ? unsuspended(ast.thunk()) : ast;
+/** The members of a union, nested and suspended ones included, or the one type otherwise. */
+const members = (ast) => {
+	const resolved = unsuspended(ast);
+	return SchemaAST.isUnion(resolved) ? resolved.types.flatMap(members) : [resolved];
+};
+/**
+* The values a literal or an enum accepts, or `undefined` for any other type, which has no
+* fixed set.
+*/
+const literalValues = (ast) => SchemaAST.isLiteral(ast) ? [ast.literal] : SchemaAST.isEnum(ast) ? ast.enums.map(([, value]) => value) : [void 0];
+/**
+* The `_tag`s a schema's encoding carries: each member's of a union, every value of a union of
+* literals or of an enum, and a suspended schema's, as a recursive error is written.
+*/
+const tagsOf = (ast) => members(SchemaAST.toEncoded(ast)).flatMap((member) => {
+	const tag = SchemaAST.isObjects(member) ? member.propertySignatures.find((property) => property.name === "_tag")?.type : void 0;
+	return tag === void 0 ? [] : members(tag).flatMap(literalValues).filter(Predicate.isString);
+});
+/**
+* Refuse an error that encodes with a built-in error's `_tag`, the built-in itself included:
+* every endpoint and tool declares the built-in errors already, a client decoding the answer
+* could not tell a look-alike from them, and a look-alike of a refusal would step up. Checked
+* where the action or the binding is made, so every surface and client of it may rely on it.
+*/
+const assertOwnTags = (what, errors) => {
+	const tag = errors.flatMap((error) => tagsOf(error.ast)).find((tag) => Object.hasOwn(statuses, tag));
+	if (tag !== void 0) throw new Error(`${what}: error _tag "${tag}" is built in, and declared on every surface`);
+};
 //#endregion
-export { answerSchemaError, assertDistinct, assertName, policyErrors, projectedErrors, selectNamed };
+export { Anyone, assertDistinct, assertKnown, assertName, assertOnce, assertOwnTags, errorList, literalValues, members, projectedErrors, unsuspended };

package/dist/internal/authentication.d.mts

@@ -0,0 +1,102 @@
+import { Anyone } from "./actions.mjs";
+import { Refusal } from "./errors.mjs";
+import { Protected, ServedRequest, Serving } from "./implementation.mjs";
+import { Action_d_exports, Any as Any$1, Errors } from "../Action.mjs";
+import { Context, Effect } from "effect";
+import { HttpRouter, HttpServerResponse } from "effect/http";
+import { HttpApiMiddleware, HttpApiSecurity } from "effect/http-api";
+//#region src/internal/authentication.d.ts
+/** One native security scheme: Bearer unless a descriptor names another. */
+export type Security = HttpApiSecurity.HttpApiSecurity;
+/** What a native scheme decodes: a `Redacted` token or key, or Basic credentials. */
+export type Credential = HttpApiSecurity.HttpApiSecurity.Type<Security>;
+/** The provider of a descriptor's verifier: a type of its own, apart from the actor. */
+export interface Provider<I, Name extends string = string> {
+  readonly "~effect-actions/Authentication": I;
+  readonly "~effect-actions/Authentication/Name": Name;
+}
+/**
+ * The native security middleware a descriptor's protected endpoints carry, which provides
+ * the identity: an identifier of its own, which no `Authentication.layer` provides, so only
+ * `ActionHttp.layer` satisfies it, from the provider.
+ */
+export interface SecurityMiddleware<I, Name extends string = string> {
+  readonly "~effect-actions/Authentication/Security": Name;
+  readonly "~effect/http-api/HttpApiMiddleware": {
+    readonly provides: I;
+    readonly requires: never;
+    readonly error: never;
+    readonly clientError: never;
+    readonly requiredForClient: false;
+  };
+}
+type Response = Effect.Effect<HttpServerResponse.HttpServerResponse, unknown, unknown>;
+interface Runtime$1 {
+  /** The descriptor the provider was built from, the one a binding naming it must hold. */
+  readonly descriptor: unknown;
+  /** The native security middleware's implementation, keyed by its scheme. */
+  readonly middleware: Readonly<Record<string, (route: Response, options: {
+    readonly credential: Credential;
+  }) => Response>>;
+  /**
+   * A protected HTTP route as it leaves the layer's middleware, a step-up refusal it fails with
+   * answered with its challenge under Bearer; as it is under another scheme.
+   */
+  readonly stepUp: HttpApiMiddleware.HttpApiMiddleware<never, never, never>;
+  readonly http: <E, R>(route: Effect.Effect<HttpServerResponse.HttpServerResponse, E, R>, optional: boolean) => Effect.Effect<HttpServerResponse.HttpServerResponse, E, R | HttpRouter.Provided>;
+  /**
+   * A route of the host's own: the request is decoded here, the route gets the identity
+   * itself, and a refusal it fails with is answered as an action route's.
+   */
+  readonly route: <E, R>(route: Effect.Effect<HttpServerResponse.HttpServerResponse, E, R>) => Effect.Effect<HttpServerResponse.HttpServerResponse, Exclude<E, Refusal>, HttpRouter.Provided>;
+}
+/**
+ * What `Authentication.make` declares: its name, the identity it authenticates, its scheme,
+ * and what its verifier may fail with besides a refusal. The `~` keys are the library's own
+ * wiring, which no host composes.
+ */
+export interface Descriptor<I, A, S extends Security, Name extends string = string, E extends Errors = readonly []> {
+  readonly name: Name;
+  readonly identity: Context.Key<I, A>;
+  readonly security: S;
+  /**
+   * What its verifier may fail with besides a refusal, as a list: every protected endpoint
+   * declares it, and every remote surface sends it with its status.
+   */
+  readonly error: E;
+  readonly "~provider": Context.Key<Provider<I, Name>, Runtime$1>;
+  readonly "~middleware": Context.Key<SecurityMiddleware<I, Name>, unknown>;
+  /** An MCP request's verified identity, which a protected tool's call promotes. */
+  readonly "~verified": Context.Key<never, unknown>;
+}
+export type Any = Descriptor<unknown, unknown, Security, string, Errors>;
+export type Identity<A extends Any$1> = [A] extends [never] ? never : A["caller"] extends Context.Key<infer I, unknown> ? I : never;
+/**
+ * The identity a descriptor for `A` must authenticate: `unknown` for an erased action, whose
+ * key is known only at run time, where `assertAuthentication` checks it.
+ */
+type Covered<A extends Any$1> = Exclude<A["caller"], typeof Anyone> extends Context.Key<infer I, unknown> ? I : never;
+export type Required<A extends Any$1> = [Protected<A>] extends [never] ? {
+  readonly authentication?: Any;
+} : {
+  readonly authentication: Descriptor<Covered<Protected<A>>, unknown, Security, string, Errors>;
+};
+export type ProviderOf<D> = D extends Descriptor<infer I, unknown, Security, infer Name, Errors> ? Provider<I, Name> : never;
+/** All protected actions on a surface use the descriptor's single identity key. */
+export type Matching<A extends Any$1, D> = unknown extends Covered<Protected<A>> ? unknown : [Exclude<Covered<Protected<A>>, D extends Descriptor<infer I, unknown, Security, string, Errors> ? I : never>] extends [never] ? unknown : {
+  readonly "Authentication descriptor does not cover every protected action": never;
+};
+/** Keep public requirements separate, without rescanning all handlers for every action. */
+export type RemoteRequest<App, A extends Any$1> = ServedRequest<App, Extract<A, {
+  readonly caller: typeof Anyone;
+}>> | Exclude<ServedRequest<App, Protected<A>>, Identity<Protected<A>>>;
+/**
+ * What a call of `A` under the descriptor `D` may fail with from its verifier: the errors `D`
+ * declares, for a protected action; none for a public one, which nothing verifies.
+ */
+export type VerifierError<A extends Any$1, D> = A["caller"] extends typeof Anyone ? never : D extends {
+  readonly error: infer E extends Errors;
+} ? E[number] : never;
+export type ServedProvider<App, A extends Any$1, D> = [Protected<Serving<App, A>>] extends [never] ? never : ProviderOf<D>;
+//#endregion
+export { Runtime$1 as Runtime };

package/dist/internal/authentication.mjs

@@ -0,0 +1,11 @@
+import { Unauthenticated } from "./errors.mjs";
+import { Anyone } from "./actions.mjs";
+import { Effect, Option } from "effect";
+//#region src/internal/authentication.ts
+const assertAuthentication = (actions, auth) => {
+	for (const action of actions) if (action.caller !== Anyone && (auth === void 0 || action.caller.key !== auth.identity.key)) throw new Error(`Protected action '${action.name}' requires its matching authentication descriptor`);
+};
+/** Remote promotion happens at tool entry, before shared dispatch, never in local calls. */
+const promote = (auth, run) => Effect.flatMap(Effect.serviceOption(auth["~verified"]), (actor) => Option.isSome(actor) ? Effect.provideService(run, auth.identity, actor.value) : Effect.fail(new Unauthenticated()));
+//#endregion
+export { assertAuthentication, promote };

package/dist/internal/call.d.mts

@@ -0,0 +1,12 @@
+import "./implementation.mjs";
+import { Action_d_exports, Any } from "../Action.mjs";
+import { Effect, Schema } from "effect";
+//#region src/internal/call.d.ts
+/**
+ * A call of `A` answering `R`. It may leave its input out when `{}` is a valid encoded input,
+ * such as for an action declared without `input` or one whose every field has a decoding
+ * default, and then sends the input `{}` decodes to. Every client shares this rule:
+ * `ActionHttp.client`, `Testing.mcpClient` and `Action.client`.
+ */
+export type Call<A extends Any, R> = {} extends A["input"]["Encoded"] ? (...input: [] | [input: A["input"]["Type"]]) => R : (input: A["input"]["Type"]) => R;
+//#endregion

package/dist/internal/call.mjs

@@ -0,0 +1,12 @@
+import { Effect, Schema } from "effect";
+//#region src/internal/call.ts
+/**
+* The input a method of `action` sends for the arguments it was called with: a given
+* argument as given, and none as the input `{}` decodes to, as a server decodes the `{}` it
+* receives. `Call` allows none only when `{}` is a valid encoded input, which is what this
+* decodes; decoding makes it one of the input's own values, such as an instance of an input
+* class, or fills its defaults.
+*/
+const inputOf = (action, args) => args.length === 0 ? Schema.decodeUnknownEffect(Schema.toCodecJson(action.input))({}) : Effect.succeed(args[0]);
+//#endregion
+export { inputOf };

package/dist/internal/cli.d.mts

@@ -1,29 +1,43 @@
-import "../Action.mjs";
-import { Effect, Schema } from "effect";
-import { Command } from "effect/cli";
+import "./errors.mjs";
+import { Action_d_exports, Any } from "../Action.mjs";
+import { Effect, Runtime, Types } from "effect";
+import { CliError, Command } from "effect/cli";
 //#region src/internal/cli.d.ts
-/** Options shared by the local and HTTP command projections. */
-interface CommonOptions<Output> {
-  /** Override the command name. The action name is used by default. */
+/**
+ * The fields of `A`'s input that may be positional: the named top-level fields of a struct
+ * or class input, as encoded. None for any other input, a record or a union included.
+ */
+export type Field<A extends Any> = A["input"]["Encoded"] extends (infer E) ? true extends Types.IsUnion<E> ? never : E extends ReadonlyArray<unknown> ? never : E extends object ? string extends keyof E ? never : Extract<keyof E, string> : never : never;
+/** How one command is named, takes its input and prints its result. */
+export interface Options<A extends Any> {
+  /** Override the command name. The action name, in kebab case, is used by default. */
   readonly name?: string;
   /** Human output. Adds a `--json` flag to the command that selects JSON instead. */
-  readonly render?: (output: Output) => string;
-}
-/** The default projection accepts a whole canonical JSON input with `--input`. */
-export interface JsonOptions<Output> extends CommonOptions<Output> {
-  readonly parameters?: never;
-  readonly input?: never;
-}
-/** Supply native CLI parameters and map their parsed values to canonical action JSON. */
-export interface ParametersOptions<Output, Parameters extends Command.Command.Config> extends CommonOptions<Output> {
-  /** Native Effect CLI flags and arguments. */
-  readonly parameters: Parameters;
-  /** Maps native parsed parameters to the action's canonical JSON input. */
-  readonly input: (parsed: Command.Command.Config.InferValue<Parameters>) => Schema.Json;
+  readonly render?: (output: A["success"]["Type"]) => string;
+  /**
+   * Input fields taken as positional arguments instead of flags, in this order. An
+   * optional field is an optional argument, so it follows every required one.
+   */
+  readonly positional?: ReadonlyArray<Field<A>>;
+  /**
+   * A short name per input field's flag, such as `{ limit: "n" }` for `-n`, given as
+   * `Param.withAlias` takes it.
+   */
+  readonly aliases?: { readonly [K in Field<A>]?: string; };
 }
 /**
- * A command either accepts whole JSON input or has explicit native CLI parameters.
- * The latter intentionally has no implicit `--input` mode.
+ * What a command fails with when its action fails: Effect CLI's own error for a handler's
+ * failure, which `Command.run` prints on stderr and marks reported, so `runMain` does not
+ * print it again. Its `cause` is the action's failure. The process exits with the cause's
+ * `Runtime.errorExitCode`, 1 by default.
  */
-export type Options<Output, Parameters extends Command.Command.Config = never> = JsonOptions<Output> | ParametersOptions<Output, Parameters>;
+export declare class UserError<out E = unknown> extends CliError.UserError {
+  readonly cause: E;
+  /**
+   * The action's failure, as Effect names an error's nested one, so the native
+   * `Effect.catchReason("UserError", "UserNotFound", f)` and `catchReasons` match it by tag.
+   */
+  get reason(): E;
+  get [Runtime.errorExitCode](): number;
+}
 //#endregion