@gjermundgaraba/effect-actions 0.19.0 → 0.21.0

package/dist/ActionHttp.d.mts

@@ -1,14 +1,20 @@
 import { Anyone } from "./contract/caller.mjs";
 import { BuiltIn, BuiltIns } from "./contract/errors.mjs";
-import { BuildError, Holding, Known, Member, MiddlewareOf, Protected, Selected, Served, Serving } from "./contract/implementation.mjs";
-import { Any, Errors } from "./Action.mjs";
-import { Any as Any$1, DescriptorOf, Identity, Matching, PublicOnly, RemoteRequest, Required, ServedProvider, ServerBuildServices, VerifierError } from "./authentication/provider.mjs";
+import { EventBuildError, EventBuildServices, EventServedRequest, HoldingEvents, ServingEvents } from "./contract/feed.mjs";
+import { Any } from "./Event.mjs";
+import { BuildError, Holding, Known, Member, MiddlewareOf, Selected, SelectedEvents, Served } from "./contract/implementation.mjs";
+import { Any as Any$1, Errors } from "./Action.mjs";
 import { Certain, ErrorsOf } from "./contract/declared.mjs";
-import { AnyHttp, Client, MethodError, Options } from "./http/client.mjs";
+import { Any as Any$2, DescriptorOf, LayerIdentity, Matching, PublicOnly, RemoteRequest, Required, ServedProvider, ServerBuildServices, VerifierError } from "./authentication/provider.mjs";
+import { Only } from "./contract/listed.mjs";
+import { SubscriptionOf } from "./contract/push.mjs";
+import { pageOf, sentOf } from "./http/events.mjs";
+import { AnyHttp, Client, MethodError, Options, WatchError } from "./http/client.mjs";
+import { SuccessOf } from "./http/streamed.mjs";
+import { Placed, placed } from "./http/placed.mjs";
 import { Context, Effect, FileSystem, Layer, Path, Schema, Types } from "effect";
 import { Etag, HttpClient, HttpClientError, HttpPlatform, HttpRouter } from "effect/http";
 import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware } from "effect/http-api";
-//#region src/http/ActionHttp.d.ts
 /** What `fetchClient` takes: `client`'s options, and the `fetch` its calls send with. */
 export interface FetchClientOptions<E = HttpClientError.HttpClientError, R = never> extends Options<E, R> {
   /**
@@ -28,29 +34,32 @@ type Through<M extends Middleware, R> = number extends M["length"] ? R | HttpApi
 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;
 };
-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 {
+type HttpLayer<H extends AnyHttp, Apps extends Served, M extends Middleware, A extends Any$1 = H["actions"][number], E extends Any = H["events"][number]> = Layer.Layer<never, BuildError<Holding<Member<Apps>, A>, A> | EventBuildError<HoldingEvents<Member<Apps>, E>, E>, ServerBuildServices<Holding<Member<Apps>, A>, A> | EventBuildServices<HoldingEvents<Member<Apps>, E>, E> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", LayerRequest<Member<Apps>, A, E, M>> | ServedProvider<Member<Apps>, A, H extends {
   readonly authentication: infer D;
-} ? D : never> | IdOf<M[number]> | Etag.Generator | FileSystem.FileSystem | HttpPlatform.HttpPlatform | Path.Path>;
+} ? D : never, ServingEvents<Member<Apps>, E>> | IdOf<M[number]> | Etag.Generator | FileSystem.FileSystem | HttpPlatform.HttpPlatform | Path.Path>;
 /** `ActionHttp.layer`'s options. */
-export interface LayerOptions<M extends Middleware = [], A extends Any = never> {
+export interface LayerOptions<M extends Middleware = [], C extends Any$1 | Any = never> {
   /**
-   * The actions it serves, among the binding's actions the implementations hold: `[GetUser]`.
-   * Defaults to every one of them.
+   * The actions and event types it serves, among the binding's the implementations hold:
+   * `[GetUser, UserRenamed]`, exactly those. Defaults to every one of them.
+   *
+   * **Gotchas**
+   *
+   * - A list naming actions alone serves no event type: each event route answers 404 until the event types are listed beside them; two layers of one binding given lists that overlap fail at startup with Effect's duplicate-route message.
    */
-  readonly actions?: ReadonlyArray<A> | undefined;
+  readonly actions?: readonly C[] | undefined;
   /**
    * Native endpoint middleware every served route runs, the first innermost: inside the
    * authentication of a protected route, outside its decoding, so it also sees invalid input.
    *
    * **Gotchas**
    *
-   * - A middleware requiring the identity needs a layer serving only protected actions: serve the public ones from a second layer without it.
+   * - A middleware requiring the identity needs a layer serving only protected actions and event types: serve the public ones from a second layer without it.
+   * - On a stream answering an action declaring `progress`, or one answering a stream, a middleware sees the call end at its first event, while its handler runs on, and never sees a later failure; what it provides lasts the handler.
    */
   readonly middleware?: M;
 }
-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)>;
+type LayerRequest<App, A extends Any$1, E extends Any, M extends Middleware> = Exclude<Through<M, RemoteRequest<App, A> | EventServedRequest<App, E>>, HttpRouter.Provided | LayerIdentity<App, A, E>>;
 /** Contract-level configuration shared by servers and clients. */
 interface Options$1<E extends Errors = Errors> {
   /**
@@ -78,20 +87,24 @@ interface Options$1<E extends Errors = Errors> {
    *
    * - One descriptor per binding: actions of a second identity take a second binding with its own `prefix`, and a public action may be in both.
    */
-  readonly authentication?: Any$1;
+  readonly authentication?: Any$2;
 }
-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;
-type Api<Actions extends ReadonlyArray<Any>, E extends Errors, D> = HttpApi.HttpApi<"actions", HttpApiGroup.HttpApiGroup<string, Endpoint<Actions[number], E, D>, true>>;
+type EndpointError<A extends Any$1, E extends Errors, D> = Schema.toCodecJson<A["error"][number] | E[number] | VerifierError<A, D> | BuiltIns>;
+type Endpoint<A extends Any$1, E extends Errors, D> = A extends Any$1 ? HttpApiEndpoint.HttpApiEndpoint<A["name"], "POST", `/${string}`, never, never, Schema.toCodecJson<A["input"]>, never, SuccessOf<A, EndpointError<A, E, D>>, EndpointError<A, E, D>> : never;
+type EventEndpoint<V extends Any, E extends Errors, D> = V extends Any ? HttpApiEndpoint.HttpApiEndpoint<V["name"], "POST", `/${string}`, never, never, Schema.toCodecJson<ReturnType<typeof SubscriptionOf<V>>>, never, Schema.toCodecJson<ReturnType<typeof pageOf<V>>> | ReturnType<typeof sentOf<V>>, Schema.toCodecJson<E[number] | VerifierError<V, D> | BuiltIns>> : never;
+type Api<Actions extends readonly Any$1[], E extends Errors, D, Events extends readonly Any[]> = HttpApi.HttpApi<"actions", HttpApiGroup.HttpApiGroup<string, Endpoint<Actions[number], E, D> | EventEndpoint<Events[number], E, D>, true>>;
 /**
- * An HTTP binding: actions, the errors every endpoint declares, and where they are mounted.
- * Plain data, so a copy of it, or one made by another installed copy of this package,
- * serves the same; `layer` serves it and `client` calls it.
+ * An HTTP binding: actions and event types, the errors every endpoint declares, and where they
+ * are mounted. Plain data, so a copy of it, or one made by another installed copy of this
+ * package, serves the same; `layer` serves it and `client` calls it.
  */
-export interface Binding<Actions extends ReadonlyArray<Any>, E extends Errors = [], D extends Any$1 | undefined = undefined> {
+export interface Binding<Actions extends readonly Any$1[], E extends Errors = [], D extends Any$2 | undefined = undefined, Events extends readonly Any[] = readonly []> {
   /** Its protected actions' authentication descriptor, or `undefined` without one. */
   readonly authentication: D;
   /** The exact actions bound to this binding. */
   readonly actions: Actions;
+  /** The exact event types bound to this binding, each at `POST <prefix>/events/<name>`. */
+  readonly events: Events;
   /** The errors every endpoint declares besides its action's own, as a list. */
   readonly error: E;
   /** Where its routes mount: `/api` by default, `/` at the root, without a trailing slash. */
@@ -108,24 +121,30 @@ export interface Binding<Actions extends ReadonlyArray<Any>, E extends Errors =
    * - Combined into one document, `HttpApi.make("app").addHttpApi(A.api).addHttpApi(B.api)`, a shared action name makes `OpenApi.fromApi` throw `Duplicate OpenAPI operationId`, and a shared prefix silently drops one binding's actions from the document and a native client: otherwise document each alone.
    * - A binding holding no protected action documents no security scheme, so Swagger shows no Authorize button.
    */
-  readonly api: Api<Actions, E, D>;
+  readonly api: Api<Actions, E, D, Events>;
 }
 /**
  * Bind actions once, for servers and clients alike, each at `POST <prefix>/<action>`, a
- * `readOnly` one too. 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 protected one also declares what its descriptor's verifier fails with.
+ * `readOnly` one too, and event types, each at `POST <prefix>/events/<name>`. 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 protected one
+ * also declares what its descriptor's verifier fails with.
  * Guide: `docs/ActionHttp.md` in this package; in an application: `examples/notes-service/src/Api.ts`.
+ *
+ * **Gotchas**
+ *
+ * - An action and an event type of one name, or an event type listed twice, throw when `make` is called: they would share a client's method.
+ * - A protected event type, where `authentication` has `principal`, is bound at `POST <prefix>/events/<name>/subscribe` and `/unsubscribe` too, for `Webhook.layer`'s delivery, and OpenAPI lists both: a binding cannot know whether its server provides that layer, and without it they answer a 409 `Event.SubscriptionError`, reason `Unsupported`.
  */
-export declare function make<const Actions extends ReadonlyArray<Any & {
+export declare function make<const Contracts extends ReadonlyArray<(Any$1 | Any) & {
   readonly caller: typeof Anyone;
-}>>(actions: Actions): Binding<Actions, [], undefined>;
-export declare function make<const Actions extends ReadonlyArray<Any>, const O extends Options$1 = {}>(actions: Actions, options: O & Required<Actions[number]> & Matching<Actions[number], NoInfer<DescriptorOf<O>>> & NoInfer<Known<O, Options$1>>): Binding<Actions, ErrorsOf<O>, DescriptorOf<O>>;
-export declare function make<const Actions extends ReadonlyArray<Any>>(actions: Actions & PublicOnly<Actions>): Binding<Actions, [], undefined>;
+}>>(contracts: Contracts): Binding<Only<Contracts, Any$1>, [], undefined, Only<Contracts, Any>>;
+export declare function make<const Contracts extends ReadonlyArray<Any$1 | Any>, const O extends Options$1 = {}>(contracts: Contracts, options: O & Required<Contracts[number]> & Matching<Contracts[number], NoInfer<DescriptorOf<O>>> & NoInfer<Known<O, Options$1>>): Binding<Only<Contracts, Any$1>, ErrorsOf<O>, DescriptorOf<O>, Only<Contracts, Any>>;
+export declare function make<const Contracts extends ReadonlyArray<Any$1 | Any>>(contracts: Contracts & PublicOnly<Contracts>): Binding<Only<Contracts, Any$1>, [], undefined, Only<Contracts, Any>>;
 /**
- * Serve the binding's actions among `implementations` in one layer, or those its `actions` lists,
- * authenticating a protected action's request before decoding it, then running its
- * implementation's `authorize` before each handler. An implementation's actions the binding
+ * Serve the binding's actions and event types among `implementations` in one layer, or those its
+ * `actions` lists, authenticating a protected action's request before decoding it, then running
+ * its implementation's `authorize` before each handler. An implementation's actions the binding
  * leaves out have no route here, one holding none of those served is not built, and a non-empty
  * list holding none of the binding's actions is refused when `layer` is called. Several layers
  * may serve one binding, each with its own `actions` and `middleware` covering its routes only.
@@ -139,18 +158,27 @@ export declare function make<const Actions extends ReadonlyArray<Any>>(actions:
  *
  * **Gotchas**
  *
- * - A success is its JSON as the body; an action without `success` answers an empty 200, no body and no content type, so a hand-written client must not parse it. One without `input` still takes the body `{}` typed as JSON: no body is a 400.
+ * - A success is its JSON as the body; an action without `success` answers an empty 200, no body and no content type, so a hand-written client must not parse it, or an empty 204 where it declares `progress`. One without `input` still takes the body `{}` typed as JSON: no body is a 400.
+ * - An action declaring `progress` answers a request whose `Accept` names `text/event-stream`, whatever else it names, with an SSE stream, listed in OpenAPI: a `progress` event for each value, its data the value's JSON, then one `final` event holding the answer's JSON, `null` for none; without that `Accept` it answers as any action, its progress dropped.
+ * - An action answering a stream, `Action.Stream`, answers an SSE stream alone, whatever `Accept` says: an `element` event for each element, its data the element's JSON, and a `progress` event for each value where it declares `progress`; a stream of none answers a 200 with no event. A failure before the first event answers its status; one after ends the stream as Effect's stream failure event, a defect as `Internal server error`.
+ * - The stream starts with the call's first event, so a failure before it, a refusal included, answers as it would without the stream; a declared failure after it ends the stream with Effect's `effect/http-api/stream/failure` event, reported as `Info` as without the stream, and a defect or an answer that does not encode with one saying `Internal server error`, its cause logged and reported.
  * - A body that is not JSON is a 400 `InvalidInput`; a request with no `Content-Type` a 415 `Unsupported content-type: none`, one with another type Effect's own 415; each after authentication on a protected route.
  * - A defect, an undeclared failure, or a success or an error that does not encode answers an empty 500: the cause goes to the log and to the call's `ErrorReporter`s, never to the body.
  * - A path no layer serves, or a method other than `POST` on a route, is a 404.
  * - The 415 keeps from every handler what another site's page can send without a CORS preflight, such as a form post carrying the user's cookie; the server's CORS policy decides the rest.
  * - Router middleware providing a request service `X` is declared `HttpRouter.middleware<{ provides: X }>()`: without the type argument it runs and the layer still owes `X`.
  * - `HttpRouter.provideRequest(layer)` builds its layer once, at startup, so it never provides an identity or a tenant.
- * - A request body is read whole, however large, unless the host provides `HttpServerRequest.MaxBodySize` to `HttpRouter.serve`, limiting every route that reads its body whole, MCP endpoints included; a body a route reads as a stream is not limited. On Node a request over it gets no response, its connection closed, never a 413; `HttpRouter.toWebHandler` ignores it, so limit bodies in the platform serving the handler.
+ * - A request body is read whole, however large, unless the host provides `HttpServerRequest.MaxBodySize` to `HttpRouter.serve`, limiting every route that reads its body whole, MCP endpoints included; a body a route reads as a stream is not limited. On Node a request over it is an empty 413 from Effect 4.0.6, and before it gets no response, its connection closed; `HttpRouter.toWebHandler` ignores it, so limit bodies in the platform serving the handler.
  * - An `ErrorReporter` the server runs with is given, as `Info`, a handler's declared failure and an input that does not decode, never a refusal or a refused credential: give an error class `override readonly [ErrorReporter.ignore] = true` to keep it out, and drop `Info` for a built-in error, which takes no mark.
+ * - An event's route takes `{ input, cursor }`, a `cursor` omitted or `null` reading from now, and answers a page, `{ events, cursor, truncated, hasMore, nextPollMs }`, or, to a request accepting `text/event-stream`, an SSE stream of `Checked`, `Occurrence`, `Gap` and `Failed` data, a `Checked` every 30 seconds; the stream carries no `id:`, so `Last-Event-ID` resumes nothing: resume from a cursor in the body.
+ * - A subscription is refused as an action's call is, before its stream starts, with the route's 401 or 403; a refusal later ends the stream with Effect's `effect/http-api/stream/failure` event.
+ * - A source's failure no refusal explains is logged and reported once, sent as a bare `Failed`, and read again from where it reached after 5 seconds, before the stream's first `Checked` too; a poll's is a 500, which `client`'s `watch` reconnects after.
+ * - A stream is read only as fast as its client reads it: a slow reader of a log source falls behind its log, and receives a `Gap`.
+ * - A protected event with a `subscription` hook needs `principal` on its descriptor to key poll subscribers: without it the layer fails to build with a message naming the event.
+ * - On a host with no lasting process, such as `HttpRouter.toWebHandler` on a serverless platform, serve check sources alone, without a `subscription` hook or `Webhook.layer`: nothing refuses the others, and under `Event.layerMemory` each instance keeps its own log of a log source, whose cursors another reads as a `Gap`, and its own leases and webhook subscriptions, lost as it ends.
  */
 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, Middleware>, H["error"]> & NoInfer<Known<O, LayerOptions<Middleware>>>): HttpLayer<H, Apps, MiddlewareOf<O, Middleware>, 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] | H["events"][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]>, SelectedEvents<O, H["events"][number]>>;
 /**
  * Effect's native `HttpApiClient` for a binding, one method per action taking the
  * action's input directly: `client.greet({ name })`, the argument omitted when `{}` is a valid
@@ -163,6 +191,11 @@ export declare function layer<const H extends AnyHttp, const Apps extends Served
  *
  * - An input that does not encode fails with `InvalidInput`, and nothing is sent; undeclared input fields, which TypeScript lets through on a wider value, are dropped as it encodes, since the server would refuse them.
  * - It interprets no status and retries nothing: a failed write may have happened, and only a declared error says what the server did.
+ * - `watch(event, input, options)` holds the event's SSE stream open, or polls its pages with `mode: "poll"`, as `Action.client`'s; a watch of an event the server does not serve, its route a 404, fails with `Event.SubscriptionError`, reason `NotServed`.
+ * - A watch reconnects after the transport fails, a status such as 503, or 60 seconds without an answer or a frame, a second later and doubling to 30 seconds, each reconnect logged as a warning; a declared error, a refusal included, ends it.
+ * - A watch's stream ends at an SSE `retry:` field, which `ActionHttp.layer` never sends, as Effect's client decodes it, and the watch connects again: a server or proxy sending one as each stream starts delivers nothing.
+ * - A call of an action declaring `progress` reads the route's event stream, as every request accepts it, and its answer from the `final` event; the server sends the values whether or not the call gave `onProgress`, and without one they are dropped.
+ * - A call of an action answering a stream returns a `Stream` of its elements, failing as the route's stream fails, with `Sse.SseError` or `Sse.Retry` too; its `onProgress` gets each `progress` event, which the server sends whether or not the call gave one.
  */
 export declare function client<const H extends AnyHttp>(binding: H, options?: Options): Effect.Effect<Client<H>, never, HttpClient.HttpClient>;
 export declare function client<const H extends AnyHttp, E, R>(binding: H, options: Options<E, R>): Effect.Effect<Client<H, E, R>, never, HttpClient.HttpClient>;
@@ -174,5 +207,4 @@ export declare function client<const H extends AnyHttp, E, R>(binding: H, option
  */
 export declare function fetchClient<const H extends AnyHttp>(binding: H, options?: FetchClientOptions): Client<H>;
 export declare function fetchClient<const H extends AnyHttp, E, R>(binding: H, options: FetchClientOptions<E, R>): Client<H, E, R>;
-//#endregion
-export { type AnyHttp as Any, type Client, type Options as ClientOptions, type MethodError, Options$1 as Options };
+export { type AnyHttp as Any, type Client, type Options as ClientOptions, type MethodError, Options$1 as Options, type Placed, type WatchError, placed };

package/dist/ActionHttp.mjs

@@ -1,15 +1,23 @@
 import { Anyone } from "./contract/caller.mjs";
 import { declared } from "./contract/status.mjs";
-import { bindingErrors, bindingOf, projectedErrors } from "./contract/declared.mjs";
-import { acquire, provideHandlers, servingOf } from "./contract/implementation.mjs";
-import { providerOf } from "./authentication/provider.mjs";
+import { bindingErrors, bindingOf, eventErrors, projectedErrors } from "./contract/declared.mjs";
+import { elementOf } from "./contract/stream.mjs";
+import { acquire } from "./contract/implementation.mjs";
 import { inputParseOptions } from "./contract/call.mjs";
+import { acquireFeeds, unkeyedHook } from "./contract/feed.mjs";
+import { offersWebhook, servedWebhooks } from "./contract/webhooks.mjs";
+import { providerOf } from "./authentication/provider.mjs";
+import { listed } from "./contract/listed.mjs";
+import { provideServed, servingOf } from "./contract/serving.mjs";
+import { answeredWithProgress, answeringElements, answeringWithProgress, elementStreamOf, progressStreamOf } from "./http/streamed.mjs";
 import { methods } from "./http/client.mjs";
+import { answering, eventEndpointOf, servedSent, webhookAnswers, webhookEndpointsOf } from "./http/events.mjs";
 import { SchemaErrors, schemaErrors } from "./http/schema-errors.mjs";
+import { placed } from "./http/placed.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/http/ActionHttp.ts
+// src/http/ActionHttp.ts
 const mountSegments = (prefix) => (prefix ?? "/api").split("/").filter((segment) => segment !== "");
 const absolutePath = (segments) => `/${segments.join("/")}`;
 const groupName = (mount) => mount.join("/") || "/";
@@ -18,24 +26,45 @@ const apiOf = (group, endpoints) => {
 	const [first, ...rest] = endpoints;
 	return HttpApi.make("actions").annotate(HttpApi.ParseOptions, { errors: "all" }).add(first === void 0 ? empty : empty.add(first, ...rest));
 };
+const successOf = (action, errors) => {
+	const element = elementOf(action.success);
+	if (element !== void 0) return elementStreamOf(element, action.progress, errors);
+	return action.progress === void 0 ? action.success : [answeredWithProgress(action.success), progressStreamOf(action.progress, action.success, errors)];
+};
 const endpointOf = (action, path, errors) => HttpApiEndpoint.post(action.name, path, {
 	payload: action.input.pipe(HttpApiSchema.asJson()),
-	success: action.success,
+	success: successOf(action, errors),
 	error: errors.map(declared)
 });
-const withinLayerMiddleware = (endpoint, middleware = []) => middleware.reduce((inner, key) => inner.middleware(key), endpoint);
-function make(actions, options = {}) {
-	const bound = bindingOf("ActionHttp binding", actions, options);
+const answerOf = (action, run) => {
+	const element = elementOf(action.success);
+	if (element !== void 0) return answeringElements(element, run);
+	return action.progress === void 0 ? run : answeringWithProgress(action.success, run);
+};
+const withinLayerMiddleware = (endpoint, middleware = []) => {
+	let within = endpoint;
+	for (const key of middleware) within = within.middleware(key);
+	return within;
+};
+function make(contracts, options = {}) {
+	const { actions, events } = listed(contracts);
+	const bound = bindingOf("ActionHttp binding", actions, events, options);
 	const mount = mountSegments(options.prefix);
 	const security = bound.authentication?.["~middleware"];
-	const endpoints = actions.map((action) => {
-		const isPublic = security === void 0 || action.caller === Anyone;
-		const endpoint = endpointOf(action, absolutePath([...mount, action.name]), bindingErrors(action, bound)).annotate(OpenApi.Description, action.description);
-		return isPublic ? endpoint : endpoint.middleware(security);
-	});
+	const secured = (endpoint, { caller }) => security === void 0 || caller === Anyone ? endpoint : endpoint.middleware(security);
+	const endpoints = [...actions.map((action) => secured(endpointOf(action, absolutePath([...mount, action.name]), bindingErrors(action, bound)).annotate(OpenApi.Description, action.description), action)), ...events.flatMap((event) => {
+		const path = absolutePath([
+			...mount,
+			"events",
+			event.name
+		]);
+		const errors = eventErrors(event, bound);
+		return [eventEndpointOf(event, path, errors), ...offersWebhook(event, bound.authentication) ? webhookEndpointsOf(event, path, errors) : []].map((endpoint) => secured(endpoint, event));
+	})];
 	const api = apiOf(groupName(mount), endpoints);
 	return {
 		actions,
+		events,
 		...bound,
 		prefix: absolutePath(mount),
 		api
@@ -50,32 +79,54 @@ var StepUp = class extends HttpApiMiddleware.Service()("effect-actions/ActionHtt
 var JsonContentType = class extends HttpApiMiddleware.Service()("effect-actions/ActionHttp/JsonContentType") {};
 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, actions, authentication } = servingOf("HTTP binding", binding, served, options);
+	const selected = servingOf("HTTP binding", binding, served, options);
+	const { apps, actions, events, eventTypes, authentication } = selected;
 	const mount = mountSegments(binding.prefix);
 	const name = groupName(mount);
-	const api = apiOf(name, actions.map((action) => {
-		const endpoint = withinLayerMiddleware(endpointOf(action, absolutePath([...mount, action.name]), projectedErrors(action, binding.error)).middleware(JsonContentType).middleware(SchemaErrors), options.middleware);
-		return action.caller === Anyone || authentication === void 0 ? endpoint : endpoint.middleware(StepUp).middleware(authentication["~middleware"]);
-	})).annotate(HttpApi.PayloadParseOptions, inputParseOptions);
+	const routed = (endpoint, { caller }) => {
+		const within = withinLayerMiddleware(endpoint.middleware(JsonContentType).middleware(SchemaErrors), options.middleware);
+		return caller === Anyone || authentication === void 0 ? within : within.middleware(StepUp).middleware(authentication["~middleware"]);
+	};
+	const api = apiOf(name, [...actions.map((action) => routed(endpointOf(action, absolutePath([...mount, action.name]), projectedErrors(action, binding.error)), action)), ...eventTypes.flatMap((event) => {
+		const path = absolutePath([
+			...mount,
+			"events",
+			event.name
+		]);
+		const errors = eventErrors(event, { error: binding.error });
+		return [eventEndpointOf(event, path, errors, servedSent), ...offersWebhook(event, authentication) ? webhookEndpointsOf(event, path, errors) : []].map((endpoint) => routed(endpoint, event));
+	})]).annotate(HttpApi.PayloadParseOptions, inputParseOptions);
 	const handlers = Layer.unwrap(Effect.gen(function* () {
-		const bound = yield* acquire(apps);
+		const bound = yield* acquire(apps, authentication);
+		const feeds = yield* acquireFeeds(events);
+		const refusal = unkeyedHook("ActionHttp", feeds, authentication?.principal !== void 0);
+		if (refusal !== void 0) return yield* Effect.die(new Error(refusal));
+		const { webhooks, offered } = yield* servedWebhooks(feeds, authentication);
 		const security = authentication === void 0 ? Layer.empty : yield* Effect.map(providerOf(authentication), (provider) => Layer.mergeAll(Layer.succeed(authentication["~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)]));
+		const webhookAnswered = offered.map((feed) => [feed.event.name, webhookAnswers(feed, authentication, webhooks)]);
+		const byName = {
+			...Object.fromEntries(bound.map(([action, run]) => {
+				const answer = answerOf(action, run);
+				return [action.name, (request) => answer(request.payload)];
+			})),
+			...Object.fromEntries(feeds.map((feed) => [feed.event.name, answering(feed, authentication)])),
+			...Object.fromEntries(webhookAnswered.map(([eventName, { subscribe }]) => [`${eventName}/subscribe`, subscribe])),
+			...Object.fromEntries(webhookAnswered.map(([eventName, { unsubscribe }]) => [`${eventName}/unsubscribe`, unsubscribe]))
+		};
 		return HttpApiBuilder.group(api, name, (builder) => builder.handleAll(byName)).pipe(Layer.provide([
-			schemaErrors(),
+			schemaErrors,
 			jsonContentType(),
 			security,
 			...hostProvidedMiddleware
 		]), buildInEmptyContext);
-	})).pipe(provideHandlers(apps));
+	})).pipe(provideServed(selected));
 	return HttpApiBuilder.layer(api).pipe(Layer.provide(handlers), Layer.provide(startupBeneathRequest()));
 }
 function client(binding, options) {
 	return methods(binding, options);
 }
 function fetchClient(binding, { fetch, ...options } = {}) {
-	return methods(binding, options).pipe(Effect.provide(FetchHttpClient.layer), Effect.provideService(FetchHttpClient.Fetch, fetch ?? ((input, init) => globalThis.fetch(input, init))), Effect.runSync);
+	return methods(binding, options).pipe(Effect.provide(FetchHttpClient.layer), Effect.provideService(FetchHttpClient.Fetch, fetch ?? (async (input, init) => await globalThis.fetch(input, init))), Effect.runSync);
 }
-//#endregion
-export { client, fetchClient, layer, make };
+export { client, fetchClient, layer, make, placed };

package/dist/ActionMcp.d.mts

@@ -1,22 +1,30 @@
-import { ActionOf, BuildError, BuildServices, Holding, Known, Member, Protected, SelectedOf, Selection, Served, ServedRequest } from "./contract/implementation.mjs";
-import { Any } from "./Action.mjs";
-import { Any as Any$1, Matching, ProviderOf, RemoteRequest, Required, ServerBuildServices } from "./authentication/provider.mjs";
-import { Client, ClientOptions, McpCallError, Params, RequestOptions, client, request } from "./mcp/client.mjs";
+import { EventBuildError, EventBuildServices, EventOf, EventRequestOf, EventServedRequest, HoldingEvents } from "./contract/feed.mjs";
+import { Any } from "./Event.mjs";
+import { ActionOf, BuildError, BuildServices, Holding, Known, Member, Protected, SelectedEventsOf, SelectedOf, Selection, Served, ServedRequest } from "./contract/implementation.mjs";
+import { Any as Any$1 } from "./Action.mjs";
+import { Any as Any$2, Matching, ProviderOf, RemoteRequest, Required, ServerBuildServices } from "./authentication/provider.mjs";
+import { McpCallError } from "./mcp/reply.mjs";
+import { Client, ClientOptions, client } from "./mcp/client.mjs";
+import { Params, RequestOptions, request } from "./mcp/request.mjs";
 import { Cause, Effect, Layer, Stdio } from "effect";
-import { McpSchema, McpServer } from "effect/ai";
 import { HttpRouter } from "effect/http";
-//#region src/mcp/ActionMcp.d.ts
+import { McpSchema, McpServer } from "effect/ai";
 /**
  * An MCP server, over HTTP or stdio: every native `McpServer.layerStdio` option but `protocols`,
  * the server information, `instructions` and `extensions` among them, the actions `A` that are
- * its tools, and the native features it serves beside them.
+ * its tools and the event types `A` it serves, and the native features it serves beside them.
  */
-export interface Options<E = never, R = never, A extends Any = Any> extends Omit<Parameters<typeof McpServer.layerStdio>[0], "protocols"> {
+export interface Options<E = never, R = never, A extends Any$1 | Any = Any$1 | Any> extends Omit<Parameters<typeof McpServer.layerStdio>[0], "protocols"> {
   /**
-   * The actions that are tools, among the implementations' actions: `[GetUser, RenameUser]`.
-   * Each keeps its implementation's authorization and builder. Defaults to every action of them.
+   * The actions that are tools and the event types it serves, among the implementations':
+   * `[GetUser, RenameUser, UserRenamed]`, exactly those. Each keeps its implementation's
+   * authorization and builder. Defaults to every action and event type of them.
+   *
+   * **Gotchas**
+   *
+   * - A list naming actions alone serves no event type: the events extension is not declared, and `events/*` answer `-32601`, until the event types are listed beside them.
    */
-  readonly actions?: ReadonlyArray<A> | undefined;
+  readonly actions?: readonly A[] | undefined;
   /**
    * Native MCP features served beside the actions' tools, such as `McpServer.resource`,
    * `McpServer.prompt` and `McpServer.toolkit` layers merged into one. They register on this
@@ -36,7 +44,7 @@ export interface Options<E = never, R = never, A extends Any = Any> extends Omit
  * `McpServer.layerHttp` option, `allowedOrigins` among them, except `protocols` and
  * `allowSessionTermination`, which are fixed.
  */
-export interface LayerHttpOptions<E = never, R = never, A extends Any = Any> extends Options<E, R, A>, Omit<Parameters<typeof McpServer.layerHttp>[0], "protocols" | "path" | "allowSessionTermination"> {
+export interface LayerHttpOptions<E = never, R = never, A extends Any$1 | Any = Any$1 | Any> extends Options<E, R, A>, Omit<Parameters<typeof McpServer.layerHttp>[0], "protocols" | "path" | "allowSessionTermination"> {
   /** The endpoint's route; defaults to `/mcp`. */
   readonly path?: HttpRouter.PathInput;
   /**
@@ -54,12 +62,16 @@ export interface LayerHttpOptions<E = never, R = never, A extends Any = Any> ext
    * - Every prompt and resource request needs a credential, listings included: to offer them signed out, serve them on an endpoint without protected tools.
    * - A handler that sends a notification starts the response, so a refusal after it is an `isError: true` tool result, not the 401 or 403 a client re-authorizes on: refuse in `authorize`.
    */
-  readonly authentication?: Any$1;
+  readonly authentication?: Any$2;
   /**
    * Whether MCP 2026-07-28 clients may subscribe, holding a stream open for list changes and
-   * resource updates. Defaults to whether `features` are given: an endpoint of actions alone
-   * registers its tools once, before any client connects, and serves no resource. Pass `true`
-   * where a handler changes the server through `McpServer.McpServer`.
+   * resource updates. Defaults to whether `features` or event implementations are given: an
+   * endpoint of actions alone registers its tools once, before any client connects, and serves no
+   * resource. Pass `true` where a handler changes the server through `McpServer.McpServer`.
+   *
+   * **Gotchas**
+   *
+   * - `false` also serves events by poll alone: Effect's server pushes no notification without subscriptions, so `events/list` lists `["poll"]` and `events/stream` answers `-32026`.
    */
   readonly allowSubscriptions?: boolean | undefined;
   /**
@@ -75,7 +87,13 @@ export interface LayerHttpOptions<E = never, R = never, A extends Any = Any> ext
 type ToolRequestContext<R> = Exclude<R, McpSchema.McpRequestContext | McpServer.McpServer>;
 type HttpToolRequestContext<R> = Exclude<ToolRequestContext<R>, HttpRouter.Provided>;
 type Features<R> = Exclude<R, McpServer.McpServer>;
-type Inferring<D, A extends Any> = [D] extends [undefined] ? [Protected<A>] extends [never] ? {
+/** The actions and event types an endpoint of `Apps` given the options `O` serves. */
+type Contracts<Apps extends Served, O> = SelectedOf<O, Apps> | SelectedEventsOf<O, Apps>;
+/** What building an endpoint of `Apps` given the options `O` may fail with. */
+type ServerError<Apps extends Served, O> = BuildError<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>> | EventBuildError<HoldingEvents<Member<Apps>, SelectedEventsOf<O, Apps>>, SelectedEventsOf<O, Apps>> | Cause.IllegalArgumentError;
+/** What building the event sources of an endpoint of `Apps` given the options `O` needs. */
+type EventServices<Apps extends Served, O> = EventBuildServices<HoldingEvents<Member<Apps>, SelectedEventsOf<O, Apps>>, SelectedEventsOf<O, Apps>>;
+type Inferring<D, A extends Pick<Any$1, "caller">> = [D] extends [undefined] ? [Protected<A>] extends [never] ? {
   readonly authentication?: undefined;
 } : unknown : {
   readonly authentication?: D;
@@ -86,21 +104,36 @@ type Inferring<D, A extends Any> = [D] extends [undefined] ? [Protected<A>] exte
  * revision opens a session with `initialize`, which holds what it sent there and no identity,
  * and lasts until that client ends it with a DELETE, answered 204, or the process stops. Protected
  * tools need `authentication`; for a serverless host, see `requestScoped`. In a tool call, what
- * middleware provides per request wins over what the endpoint was built with.
- * Guide: `docs/ActionMcp.md` in this package; in an application: `examples/mcp-tools/`.
+ * middleware provides per request wins over what the endpoint was built with. The event
+ * types among `implementations`, or those `actions` lists, are served as SEP-3415 events,
+ * `events/list`, `events/poll` and `events/stream`, and, where `Webhook.layer` is provided, `events/subscribe`
+ * and `events/unsubscribe`: experimental, as that extension is a draft, pinned to its PR head
+ * 2ec39b9c49c583411b73cb460dea5f52b5c541a6.
+ * Guide: `docs/ActionMcp.md` in this package; in an application: `examples/mcp-tools/`, and
+ * `examples/build-events/` for events.
  *
  * **Gotchas**
  *
  * - A success is `isError: false` with `structuredContent` its JSON and the same JSON as one text block, both `null` for an action without `success`; an `Action.Image` field is left out of `structuredContent` and its text, its block following them, and a success of images alone has no `structuredContent`.
  * - A declared error is an `isError: true` tool result in a 200 holding its JSON as one text block, with no `structuredContent`; a refusal is answered as `Action.Unauthenticated` and `Action.Forbidden` say.
+ * - An action answering a stream, `Action.Stream`, answers its elements collected into one array once the stream ends, a success of that array.
+ * - An action declaring `progress` sends each value as `notifications/progress` on the `progressToken` its call's `_meta` carries, before the result: `progress` counts from 1, `message` is the value's JSON and `_meta["effect-actions/progress"]` the value; a call without a token gets none.
  * - Arguments that do not decode never reach the handler: an `isError: true` result in a 200, text `Invalid parameters for tool '<name>': …`, or for a 2025-06-18 client a JSON-RPC error.
  * - A defect, an undeclared failure, or a success or an error that does not encode is `isError: true`, text `Tool execution failed due to an internal server error.`: the cause goes to the log and to the call's `ErrorReporter`s, never to the client.
  * - An unknown tool is a JSON-RPC error `-32602` in a 200; a body that is not JSON a JSON-RPC error `-32700` in a 200; a `Content-Type` missing or not JSON an empty 415; another HTTP method an empty 405 with `Allow: POST, DELETE`, `Allow: POST` where `requestScoped`, or the 401 of an endpoint with authentication when signed out.
  * - A 2025-11-25 or 2025-06-18 client gets `structuredContent` only for a success that is an object: any other success arrives as its text block alone, a string unquoted.
  * - A client asking for an earlier revision, such as 2025-03-26, is offered 2025-11-25, so a client speaking only that earlier one cannot connect.
  * - A request body is read whole, however large, and a 2025 session holds what its `initialize` sent until it ends, so an oversized `initialize` costs memory for that long: limit bodies as `ActionHttp.layer` says.
+ * - An event type named starting with `mcp.`, a prefix MCP keeps for its own events, is refused as the endpoint is made, with `MCP event name starts with "mcp."`.
+ * - Events are 2026-07-28's alone: a 2025 session gets `-32601` for `events/*`, and its `initialize` advertises no events extension.
+ * - With `requestScoped`, `events/stream` answers `-32026`, no server outliving a request to push, so events are served by poll, and by webhook where `Webhook.layer` is provided; their sources, logs, `subscription` hooks' leases and webhook subscriptions are built once with the endpoint, as without it.
+ * - On a host with no lasting process, such as a serverless platform, serve check sources alone, without a `subscription` hook: nothing refuses the others, and under `Event.layerMemory` each instance keeps its own log of a log source, whose cursors another reads as a gap, and its own leases, lost as it ends.
+ * - A protected event with a `subscription` hook needs `principal` on `authentication`, or the endpoint is refused at startup: a poll's hook is held per principal between requests.
+ * - A push stream holds its request open while it is read, a heartbeat every 30 seconds: a host's request timeout ends it, and `client`'s `watch` reconnects from its cursor.
+ * - A poll's `maxEvents` caps a log source's page, at most 100, and is not honored for a check source, whose page is answered whole since only its last cursor resumes; `maxAgeMs` is accepted and not honored, a log source keeping what its `log.maxAge` and `log.maxEvents` say.
+ * - A push stream's failure that no refusal explains, such as an upstream's outage, is `notifications/events/error`, its cause logged and reported, and the stream resumes from where it reached after 5 seconds; a refusal ends it with `notifications/events/terminated`. One before `active`, or a poll's, is a JSON-RPC `-32603`, which `client`'s `watch` reconnects after, as after a 5xx.
  */
-export declare function layerHttp<const Apps extends Served, const O extends Selection<ActionOf<Member<Apps>>> = {}, E = never, R = never, const D extends Any$1 | undefined = undefined>(implementations: Apps, options: LayerHttpOptions<E, R, ActionOf<Member<Apps>>> & O & NoInfer<Known<O, LayerHttpOptions<E, R, Any>>> & NoInfer<Required<SelectedOf<O, Apps>>> & Matching<NoInfer<SelectedOf<O, Apps>>, NoInfer<D>> & Inferring<D, NoInfer<SelectedOf<O, Apps>>>): Layer.Layer<never, BuildError<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>> | Cause.IllegalArgumentError | E, ServerBuildServices<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", HttpToolRequestContext<RemoteRequest<Member<Apps>, SelectedOf<O, Apps>>>> | ProviderOf<D> | Features<R>>;
+export declare function layerHttp<const Apps extends Served, const O extends Selection<ActionOf<Member<Apps>> | EventOf<Member<Apps>>> = {}, E = never, R = never, const D extends Any$2 | undefined = undefined>(implementations: Apps, options: LayerHttpOptions<E, R, ActionOf<Member<Apps>> | EventOf<Member<Apps>>> & O & NoInfer<Known<O, LayerHttpOptions<E, R>>> & NoInfer<Required<Contracts<Apps, O>>> & Matching<NoInfer<Contracts<Apps, O>>, NoInfer<D>> & Inferring<D, NoInfer<Contracts<Apps, O>>>): Layer.Layer<never, ServerError<Apps, O> | E, ServerBuildServices<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>> | EventServices<Apps, O> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", HttpToolRequestContext<RemoteRequest<Member<Apps>, SelectedOf<O, Apps>> | EventServedRequest<Member<Apps>, SelectedEventsOf<O, Apps>>>> | ProviderOf<D> | Features<R>>;
 /**
  * Serve MCP tools through newline-delimited JSON-RPC on standard I/O, speaking MCP
  * 2026-07-28, 2025-11-25 or 2025-06-18, as the host negotiates: the whole
@@ -109,14 +142,13 @@ export declare function layerHttp<const Apps extends Served, const O extends Sel
  * go to stderr, since stdout carries the protocol. The host supplies the `Stdio` service, and
  * provides the identity around `runStdio`; arguments are tool input only and never establish
  * request identity or authority, and each implementation's `authorize` runs for its protected
- * actions. Its tool results, and how it answers each revision and an earlier one asked for, are
- * `layerHttp`'s.
+ * actions and events. Its tool results, its events, and how it answers each revision and an
+ * earlier one asked for, are `layerHttp`'s.
  *
  * **Gotchas**
  *
  * - A line that is not JSON goes unanswered, with no `-32700` as over HTTP, and the lines after it are still answered.
  * - The layers provided around it log to stdout, among the protocol's lines: apply `ActionCli.logToStderr` to the program, last, as its JSDoc says.
  */
-export declare function runStdio<const Apps extends Served, const O extends Selection<ActionOf<Member<Apps>>> = {}, E = never, R = never>(implementations: Apps, options: Options<E, R, ActionOf<Member<Apps>>> & O & NoInfer<Known<O, Options<E, R, Any>>>): Effect.Effect<void, BuildError<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>> | Cause.IllegalArgumentError | E, BuildServices<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>> | Stdio.Stdio | ToolRequestContext<ServedRequest<Member<Apps>, SelectedOf<O, Apps>>> | Features<R>>;
-//#endregion
+export declare function runStdio<const Apps extends Served, const O extends Selection<ActionOf<Member<Apps>> | EventOf<Member<Apps>>> = {}, E = never, R = never>(implementations: Apps, options: Options<E, R, ActionOf<Member<Apps>> | EventOf<Member<Apps>>> & O & NoInfer<Known<O, Options<E, R>>>): Effect.Effect<void, ServerError<Apps, O> | E, BuildServices<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>> | EventServices<Apps, O> | Stdio.Stdio | ToolRequestContext<ServedRequest<Member<Apps>, SelectedOf<O, Apps>> | EventRequestOf<Member<Apps>, SelectedEventsOf<O, Apps>>> | Features<R>>;
 export { type Client, type ClientOptions, McpCallError, type Params, type RequestOptions, client, request };