@gjermundgaraba/effect-actions 0.19.0 → 0.21.0

package/dist/contract/watch.d.mts

@@ -0,0 +1,18 @@
+import "./pages.mjs";
+import { Any, WatchOptions, WebhookDelivery } from "../Event.mjs";
+import { Receiving } from "./receiving.mjs";
+import "./subscribe.mjs";
+import { Effect, Schema, Stream } from "effect";
+/**
+ * The arguments of `watch(event, ...)` after the event: its input, which may be left out when
+ * `{}` is a valid encoded input, as for an action's call, and the watch's options `O`, whose
+ * `resume` store may fail with `SE`.
+ */
+export type WatchArgs<E extends Any, SE, O extends WatchOptions<unknown> = WatchOptions<SE>> = {} extends E["input"]["Encoded"] ? [input?: E["input"]["Type"], options?: O & WatchOptions<SE>] : [input: E["input"]["Type"], options?: O & WatchOptions<SE>];
+/**
+ * What a watch given the options `O` requires beyond its client's: the receiver, where its `mode`
+ * may be a `Webhook.delivery`.
+ */
+export type WatchRequirement<O> = O extends {
+  readonly mode?: infer M;
+} ? [Extract<M, WebhookDelivery>] extends [never] ? never : Receiving : never;

package/dist/contract/watch.mjs

@@ -0,0 +1,105 @@
+import { Checked, Gap } from "./occurrence.mjs";
+import { paged } from "./pages.mjs";
+import { SubscriptionError, Unsupported } from "../Event.mjs";
+import { watchParameter } from "./receiving.mjs";
+import { makeRecent } from "./recent.mjs";
+import { CallbackUrl } from "./callback.mjs";
+import { Cause, Clock, Duration, Effect, Predicate, Queue, Schedule, Schema, Stream } from "effect";
+// src/contract/watch.ts
+const reconnectDelay = Duration.seconds(1);
+const maxReconnectDelay = Duration.seconds(30);
+const afterFailures = (transient) => Schedule.min([Schedule.exponential(reconnectDelay), Schedule.spaced(maxReconnectDelay)]).pipe(Schedule.setInputType(), Schedule.while(({ input }) => transient(input)), Schedule.tap(({ input, duration }) => Effect.logWarning(`A watch reconnects in ${Duration.format(duration)} after a failure`, input)));
+const isSubscriptionError = Schema.is(SubscriptionError);
+/** Whether a watch's failure says the server serves its event by poll alone, refusing to push it. */
+const pushRefused = Predicate.compose(isSubscriptionError, ({ reason }) => Predicate.isTagged(reason, "Unsupported") && reason.feature === "deliveryMode" && reason.value === "push");
+const dedupeWindow = 1e3;
+const capacity = 16;
+const unsubscribeTimeout = Duration.seconds(5);
+/**
+* One webhook subscription from `cursor`, read from `received`, where its receiver puts each
+* body: each grant, the subscribe's and each refresh's when half of it is left, is put there too,
+* behind what was accepted before it, so its position is kept in order; a refresh's failure is
+* put there as well, and ends the run where it is read.
+*/
+const delivered = (webhook, request, received, cursor) => {
+	let at = cursor;
+	const subscribed = Effect.suspend(() => webhook.subscribe({
+		...request,
+		cursor: at
+	})).pipe(Effect.tap((grant) => Queue.offer(received, Effect.succeed([grant.truncated ? Gap.make({ cursor: grant.cursor }) : Checked.make({ cursor: grant.cursor })]))));
+	const refreshed = (refreshBefore) => refreshBefore === null ? Effect.never : Effect.flatMap(Clock.currentTimeMillis, (now) => Effect.andThen(Effect.sleep(Duration.millis(Math.max(0, (Date.parse(refreshBefore) - now) / 2))), Effect.flatMap(subscribed, (grant) => refreshed(grant.refreshBefore))));
+	return Stream.unwrap(Effect.gen(function* () {
+		const grant = yield* subscribed;
+		yield* Effect.forkScoped(Effect.catchCause(refreshed(grant.refreshBefore), (cause) => Cause.hasInterruptsOnly(cause) ? Effect.void : Queue.offer(received, Effect.failCause(cause))));
+		return Stream.fromEffectRepeat(Effect.flatten(Queue.take(received))).pipe(Stream.flattenIterable, Stream.tap((fed) => Effect.sync(() => {
+			at = fed.cursor ?? at;
+		})));
+	}));
+};
+/**
+* The occurrences and gaps of one subscription, as every client's `watch` answers them. Each run
+* starts from `options`: what one run saw, the cursor and the ids it deduplicates by, ends with
+* it, and only `resume` carries a cursor to the next.
+*/
+const watching = (transport, { cursor: given, mode, resume } = {}) => {
+	const reconnecting = (open, cursor, polled) => {
+		const { transient } = transport;
+		let at = cursor;
+		const once = Stream.suspend(() => open(at)).pipe(Stream.tap((fed) => Effect.sync(() => {
+			at = fed.cursor ?? at;
+		})));
+		const reopened = transient === void 0 ? once : once.pipe(Stream.repeat(Schedule.spaced(reconnectDelay)), Stream.retry(afterFailures(transient)));
+		return polled === void 0 ? reopened : reopened.pipe(Stream.catchIf(pushRefused, () => Stream.suspend(() => polled(at))));
+	};
+	const polled = (cursor) => reconnecting((at) => paged(transport.poll, at), cursor);
+	const webhooked = ({ baseUrl, ttl }, cursor) => Stream.unwrap(Effect.gen(function* () {
+		const { webhook } = transport;
+		if (webhook === void 0) return yield* SubscriptionError.of(transport.name, new Unsupported({
+			feature: "deliveryMode",
+			value: "webhook"
+		}));
+		const base = yield* Schema.decodeEffect(CallbackUrl)(baseUrl);
+		const receiving = yield* webhook.receiver;
+		const received = yield* Queue.unbounded();
+		const { id, secret } = yield* receiving.register((body) => Queue.sizeUnsafe(received) < capacity && Queue.offerUnsafe(received, webhook.read(body)));
+		const url = new URL(`${base.pathname.replace(/\/$/u, "")}${receiving.path}`, base);
+		url.searchParams.set(watchParameter, id);
+		const request = {
+			delivery: {
+				url,
+				secret
+			},
+			ttlMs: ttl === void 0 ? void 0 : Duration.toMillis(Duration.fromInputUnsafe(ttl))
+		};
+		yield* Effect.addFinalizer(() => webhook.unsubscribe({ delivery: { url } }).pipe(Effect.timeout(unsubscribeTimeout), Effect.ignore));
+		return reconnecting((at) => delivered(webhook, request, received, at), cursor);
+	}));
+	return Stream.suspend(() => {
+		const seen = makeRecent(dedupeWindow);
+		let pending = null;
+		const keep = (cursor) => cursor === null || resume === void 0 ? Effect.void : resume.store.set(resume.key, cursor);
+		const fresh = (eventId) => {
+			if (seen.has(eventId)) return false;
+			seen.add(eventId);
+			return true;
+		};
+		const handled = Effect.fnUntraced(function* (fed) {
+			yield* keep(pending);
+			pending = null;
+			if (Predicate.isTagged(fed, "Checked")) {
+				yield* keep(fed.cursor);
+				return [];
+			}
+			if (Predicate.isTagged(fed, "Gap")) return [fed];
+			pending = fed.cursor;
+			return fresh(fed.eventId) ? [fed] : [];
+		});
+		const start = given !== void 0 || resume === void 0 ? Effect.succeed(given ?? null) : Effect.map(resume.store.get(resume.key), (kept) => kept ?? null);
+		return Stream.unwrap(Effect.map(start, (cursor) => {
+			if (Predicate.isTagged(mode, "WebhookDelivery")) return webhooked(mode, cursor);
+			if (mode === "poll") return polled(cursor);
+			return reconnecting(transport.stream, cursor, mode === "stream" ? void 0 : polled);
+		})).pipe(Stream.rechunk(1), Stream.mapEffect(handled), Stream.catchCause((cause) => Cause.hasInterruptsOnly(cause) ? Stream.failCause(cause) : Stream.concat(Stream.fromEffectDrain(keep(pending)), Stream.failCause(cause))), Stream.flattenIterable);
+	});
+};
+export { watching };

package/dist/contract/webhooks.d.mts

@@ -0,0 +1,42 @@
+import { Anyone, Named } from "./caller.mjs";
+import { Feed } from "./feed.mjs";
+import { Any } from "../Event.mjs";
+import { AnyWebhookCancellation, AnyWebhookSubscription, Subscribed } from "./subscribe.mjs";
+import { Context, Effect, Option } from "effect";
+/** An event type a surface may offer by webhook: a protected one, its caller an identity. */
+export type Protected = Any & {
+  readonly caller: Exclude<Any["caller"], typeof Anyone>;
+};
+/** A feed a surface offers by webhook: one of a protected event type. */
+export interface WebhookFeed extends Feed {
+  readonly event: Protected;
+}
+/** Which webhook subscription a request names: the subscriber, the event, its input, the URL. */
+export interface Subscription extends AnyWebhookCancellation {
+  readonly feed: WebhookFeed;
+  readonly principal: string;
+}
+/**
+ * A request to start or refresh a webhook subscription, as its surface decoded it, `keyed` the
+ * surface's authentication, whose `schema` keeps the subscriber's identity.
+ */
+export interface Subscribing extends AnyWebhookSubscription {
+  readonly feed: WebhookFeed;
+  readonly principal: string;
+  readonly keyed: Named;
+}
+declare const Webhooks_base: Context.ServiceClass<Webhooks, "effect-actions/Webhooks", {
+  readonly serve: (feeds: readonly WebhookFeed[], keyed: Named) => Effect.Effect<void, never, unknown>;
+  readonly subscribe: (subscribing: Subscribing) => Effect.Effect<Subscribed, unknown, unknown>;
+  readonly unsubscribe: (subscription: Subscription) => Effect.Effect<void, unknown, unknown>;
+}>;
+/**
+ * Where a surface's webhook subscriptions are held and delivered from: `Webhook.layer` provides
+ * it, and a surface offers webhook delivery only where it is. A surface `serve`s the feeds it
+ * offers by webhook as it builds, with its authentication, which restores their kept
+ * subscriptions, and dies where they cannot be kept. `subscribe` runs as the subscriber, whose
+ * context each delivery runs in; it fails as the feed's admission does, or with
+ * `Event.SubscriptionError`.
+ */
+export declare class Webhooks extends Webhooks_base {}
+export {};

package/dist/contract/webhooks.mjs

@@ -0,0 +1,53 @@
+import { Anyone, isNamed } from "./caller.mjs";
+import { SubscriptionError, Unsupported } from "../Event.mjs";
+import { Context, Effect, Option } from "effect";
+// src/contract/webhooks.ts
+/**
+* Where a surface's webhook subscriptions are held and delivered from: `Webhook.layer` provides
+* it, and a surface offers webhook delivery only where it is. A surface `serve`s the feeds it
+* offers by webhook as it builds, with its authentication, which restores their kept
+* subscriptions, and dies where they cannot be kept. `subscribe` runs as the subscriber, whose
+* context each delivery runs in; it fails as the feed's admission does, or with
+* `Event.SubscriptionError`.
+*/
+var Webhooks = class extends Context.Service()("effect-actions/Webhooks") {};
+const isProtected = (event) => event.caller !== Anyone;
+/** Whether a surface offers `event` by webhook: a protected event, its subscribers `keyed`. */
+const offersWebhook = (event, keyed) => isProtected(event) && isNamed(keyed);
+/**
+* Serves the feeds among `feeds` a surface offers by webhook, its subscribers `keyed`, to the
+* `Webhooks` it is given, as it builds: restoring their kept subscriptions, and dying where they
+* cannot be kept. Answers the service, where given, and those feeds.
+*/
+const servedWebhooks = (feeds, keyed) => Effect.gen(function* () {
+	const webhooks = yield* Effect.serviceOption(Webhooks);
+	const offered = feeds.filter((feed) => offersWebhook(feed.event, keyed));
+	if (Option.isSome(webhooks) && isNamed(keyed)) yield* webhooks.value.serve(offered, keyed);
+	return {
+		webhooks,
+		offered
+	};
+});
+/**
+* The webhook subscriber calling a subscribe or unsubscribe of `feed`'s event on a surface given
+* `webhooks`, its subscribers `keyed`; `Unsupported` where the surface does not offer it by
+* webhook.
+*/
+const webhookSubscriber = (feed, keyed, webhooks) => {
+	const { event } = feed;
+	if (Option.isNone(webhooks) || !isNamed(keyed) || !isProtected(event)) return Effect.fail(SubscriptionError.of(event.name, new Unsupported({
+		feature: "deliveryMode",
+		value: "webhook"
+	})));
+	const service = webhooks.value;
+	return Effect.map(Effect.service(event.caller), (identity) => ({
+		webhooks: service,
+		feed: {
+			...feed,
+			event
+		},
+		keyed,
+		principal: keyed.principal(identity)
+	}));
+};
+export { Webhooks, offersWebhook, servedWebhooks, webhookSubscriber };

package/dist/http/client.d.mts

@@ -1,11 +1,17 @@
+import { Codec } from "../contract/codec.mjs";
 import { BuiltIns } from "../contract/errors.mjs";
+import { Any, Received, SubscriptionError, WatchOptions } from "../Event.mjs";
+import "../contract/implementation.mjs";
 import { Call } from "../contract/call.mjs";
-import { Any, Errors } from "../Action.mjs";
-import { Any as Any$1, VerifierError } from "../authentication/provider.mjs";
-import { Effect, Schema } from "effect";
+import { Answer, StreamOf } from "../contract/stream.mjs";
+import "../contract/receiving.mjs";
+import { WatchArgs, WatchRequirement } from "../contract/watch.mjs";
+import { Any as Any$1, Errors } from "../Action.mjs";
+import { Any as Any$2, VerifierError } from "../authentication/provider.mjs";
+import { sentOf } from "./events.mjs";
+import { Effect, Schema, Stream } from "effect";
 import { HttpClient, HttpClientError } from "effect/http";
 import { HttpApi, HttpApiClient } from "effect/http-api";
-//#region src/http/client.d.ts
 /**
  * The native `HttpApiClient.make` options except `transformResponse`, which may change a call's
  * success, failure or services the method types cannot follow: `baseUrl`, and `transformClient`,
@@ -32,31 +38,48 @@ export interface Options<E = HttpClientError.HttpClientError, R = never> {
   readonly transformClient?: ((client: HttpClient.HttpClient) => HttpClient.HttpClient.With<E, R>) | undefined;
 }
 type BindingError = Errors[number];
+type SseFailure = Extract<Stream.Error<HttpApiClient.SuccessType<ReturnType<typeof sentOf<Any>>>>, {
+  readonly _tag: "SseError" | "Retry";
+}>;
+type SseError = Extract<SseFailure, {
+  readonly _tag: "SseError";
+}>;
 /**
  * What one call of `A` fails with: a declared error value (the action's own, one `E` of the
  * binding's, or a built-in `InvalidInput`, `Unauthenticated` or `Forbidden`), a native
  * `HttpClientError` for a failed request or an undeclared answer, or a `SchemaError` when
- * the success does not decode.
+ * the success does not decode. A call reading an event stream, of an action answering a stream or
+ * declaring `progress`, also fails with Effect's `Sse.SseError` or `Sse.Retry`.
  */
-export type MethodError<A extends Any, E extends BindingError = never> = A["error"][number]["Type"] | E["Type"] | BuiltIns["Type"] | HttpClientError.HttpClientError | Schema.SchemaError;
-type Method<A extends Any, E extends BindingError, CE, CR> = Call<A, Effect.Effect<A["success"]["Type"], MethodError<A, E> | CE, CR>>;
+export type MethodError<A extends Any$1, E extends BindingError = never> = A["error"][number]["Type"] | E["Type"] | BuiltIns["Type"] | HttpClientError.HttpClientError | Schema.SchemaError | (A["progress"] extends undefined ? A["success"] extends StreamOf<Codec> ? SseFailure : never : SseFailure);
+type Method<A extends Any$1, E extends BindingError, CE, CR> = Call<A, Answer<A["success"], MethodError<A, E> | CE, CR>>;
 /**
  * Any HTTP binding, with its actions erased: what `layer` and `client` read. The API is a native
  * constraint here because native groups are invariant in their endpoints; `actions` carries the
  * types.
  */
 export interface AnyHttp {
-  readonly authentication?: Any$1 | undefined;
-  readonly actions: ReadonlyArray<Any>;
-  readonly error: ReadonlyArray<BindingError>;
+  readonly authentication?: Any$2 | undefined;
+  readonly actions: readonly Any$1[];
+  readonly events: readonly Any[];
+  readonly error: readonly BindingError[];
   readonly prefix: `/${string}`;
   readonly api: HttpApi.Constraint;
 }
+/**
+ * What a watch of `W` over the binding `H` may fail with: what its route's first answer declares,
+ * a refusal ending it later, an `Event.SubscriptionError` where it is not served, a native
+ * `HttpClientError` that no reconnect outlasts, or a stream or an occurrence that does not decode.
+ */
+export type WatchError<W extends Any, H extends AnyHttp> = SubscriptionError | BuiltIns["Type"] | H["error"][number]["Type"] | VerifierError<W, H["authentication"]>["Type"] | HttpClientError.HttpClientError | Schema.SchemaError | SseError;
+type Watching<H extends AnyHttp, E, R> = [H["events"][number]] extends [never] ? unknown : {
+  readonly watch: <W extends H["events"][number], SE = never, const O extends WatchOptions<unknown> = {}>(event: W, ...args: WatchArgs<W, SE, O>) => Stream.Stream<Received<W>, WatchError<W, H> | E | SE, R | WatchRequirement<O>>;
+};
 /**
  * Every action of the binding `H`, as `client.<action>(input)`: a protected one may also fail
- * with what its descriptor's verifier declares. Each call also fails with `E` and requires `R`,
- * what its `transformClient` adds.
+ * with what its descriptor's verifier declares. Where `H` lists event types, `watch(event, input,
+ * options)` subscribes to one. Each call and watch also fails with `E` and requires `R`, what its
+ * `transformClient` adds.
  */
-export type Client<H extends AnyHttp, E = never, R = never> = { readonly [A in H["actions"][number] as A["name"]]: Method<A, H["error"][number] | VerifierError<A, H["authentication"]>, E, R>; };
-//#endregion
+export type Client<H extends AnyHttp, E = never, R = never> = { readonly [A in H["actions"][number] as A["name"]]: Method<A, H["error"][number] | VerifierError<A, H["authentication"]>, E, R>; } & Watching<H, E, R>;
 export {};

package/dist/http/client.mjs

@@ -1,19 +1,57 @@
-import { checked } from "../contract/call.mjs";
-import { Effect } from "effect";
-import { HttpClient } from "effect/http";
+import { elementOf } from "../contract/stream.mjs";
+import { checked, checkedStream, sendingValue, watchInput } from "../contract/call.mjs";
+import { watching } from "../contract/watch.mjs";
+import { readElements, readWithProgress } from "./streamed.mjs";
+import { transportOf } from "./watch.mjs";
+import { Effect, Stream } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/http";
 import { HttpApiClient } from "effect/http-api";
-//#region src/http/client.ts
-const methodsWith = (http, httpClient, baseUrl) => Effect.map(HttpApiClient.makeWith(http.api, {
+// src/http/client.ts
+const methodOf = (native, name, what) => {
+	const method = native[name];
+	if (method === void 0) throw new Error(`No client method for ${name} (use the binding \`ActionHttp.make\` returned, whose group holds this ${what})`);
+	return method;
+};
+const acceptingStreams = HttpClient.mapRequest(HttpClientRequest.setHeader("accept", "application/json, text/event-stream"));
+const nativeOf = (http, httpClient, baseUrl) => HttpApiClient.makeWith(http.api, {
 	baseUrl,
 	httpClient
-}), (client) => {
-	const native = client;
-	return Object.fromEntries(http.actions.map((action) => {
-		const method = native[action.name];
-		if (method === void 0) throw new Error(`No client method for ${action.name} (use the binding \`ActionHttp.make\` returned, whose group holds this action)`);
-		return [action.name, checked(action, (payload) => method({ payload }))];
-	}));
+});
+const actionMethodOf = (action, native) => {
+	const method = methodOf(native, action.name, "action");
+	if (elementOf(action.success) !== void 0) return checkedStream(action, sendingValue, (payload, onProgress) => Stream.unwrap(Effect.map(method({ payload }), (answer) => readElements(answer, onProgress))));
+	if (action.progress === void 0) return checked(action, sendingValue, (payload) => method({ payload }));
+	return checked(action, sendingValue, (payload, onProgress) => Effect.flatMap(method({ payload }), (answer) => readWithProgress(answer, onProgress)));
+};
+/** The `Senders` of `http` over `httpClient`: its native clients, built once. */
+const sendersWith = (http, httpClient, baseUrl) => Effect.gen(function* () {
+	const native = yield* nativeOf(http, acceptingStreams(httpClient), baseUrl);
+	const plain = yield* nativeOf(http, httpClient, baseUrl);
+	const polls = plain;
+	const streams = native;
+	const subscribes = plain;
+	const unsubscribes = plain;
+	const webhookOf = (name) => {
+		const subscribe = subscribes[`${name}/subscribe`];
+		const unsubscribe = unsubscribes[`${name}/unsubscribe`];
+		return subscribe === void 0 || unsubscribe === void 0 ? void 0 : {
+			subscribe,
+			unsubscribe
+		};
+	};
+	return {
+		method: (action) => actionMethodOf(action, native),
+		transport: (event, input) => transportOf(event, methodOf(polls, event.name, "event"), methodOf(streams, event.name, "event"), webhookOf(event.name), input)
+	};
+});
+const methodsWith = (http, httpClient, baseUrl) => Effect.map(sendersWith(http, httpClient, baseUrl), ({ method, transport }) => {
+	const actions = Object.fromEntries(http.actions.map((action) => [action.name, method(action)]));
+	if (http.events.length === 0) return actions;
+	const watch = (event, input, options) => Stream.unwrap(Effect.map(watchInput(event, input), ({ value }) => watching(transport(event, value), options)));
+	return {
+		...actions,
+		watch
+	};
 });
 const methods = (http, { baseUrl, transformClient } = {}) => Effect.flatMap(HttpClient.HttpClient, (native) => transformClient === void 0 ? methodsWith(http, native, baseUrl) : methodsWith(http, transformClient(native), baseUrl));
-//#endregion
-export { methods };
+export { methods, sendersWith };

package/dist/http/events.d.mts

@@ -0,0 +1,56 @@
+import "../contract/codec.mjs";
+import { Forbidden, Unauthenticated } from "../contract/errors.mjs";
+import { OccurrenceSchema } from "../contract/occurrence.mjs";
+import "../contract/pages.mjs";
+import "../contract/feed.mjs";
+import { Any } from "../Event.mjs";
+import "../contract/subscribe.mjs";
+import "../Action.mjs";
+import "../authentication/provider.mjs";
+import "../contract/push.mjs";
+import "../contract/webhooks.mjs";
+import { Effect, Option, Schema, Stream } from "effect";
+import { HttpApiEndpoint, HttpApiSchema } from "effect/http-api";
+/**
+ * One poll's answer: the occurrences since the cursor, and when to ask again, sent as
+ * `nextPollMs`, its milliseconds.
+ */
+export declare const pageOf: <E extends Any>(event: E) => Schema.encodeKeys<Schema.Struct<{
+  readonly events: Schema.$Array<OccurrenceSchema<E>>;
+  readonly cursor: Schema.NullOr<Schema.String>;
+  readonly truncated: Schema.Boolean;
+  readonly hasMore: Schema.Boolean;
+  readonly nextPoll: Schema.DurationFromMillis;
+}>, {
+  readonly nextPoll: "nextPollMs";
+}>;
+/**
+ * What a subscription's event stream sends, each as one SSE `message`: a `Checked` with the
+ * position it starts from, or a `Gap` where that was no longer served, then each occurrence, a
+ * `Gap` where some were missed, a `Checked` every 30 seconds, and a `Failed` where reading
+ * failed and resumes. A later refusal ends it, as Effect's stream failure event.
+ */
+export declare const sentOf: <E extends Any>(event: E) => HttpApiSchema.StreamSse<HttpApiSchema.SseEventFromData<Schema.toCodecJson<Schema.Union<readonly [OccurrenceSchema<E>, Schema.TaggedStruct<"Gap", {
+  readonly cursor: Schema.NullOr<Schema.String>;
+}>, Schema.TaggedStruct<"Checked", {
+  readonly cursor: Schema.NullOr<Schema.String>;
+}>, Schema.TaggedStruct<"Failed", {}>]>>>, Schema.Union<readonly [typeof Unauthenticated, typeof Forbidden]>, {
+  readonly _tag: "Gap";
+  readonly cursor: string | null;
+} | {
+  readonly _tag: "Checked";
+  readonly cursor: string | null;
+} | {
+  readonly _tag: "Failed";
+} | Schema.Struct.View<{
+  readonly _tag: Schema.tag<"Occurrence">;
+  eventId: Schema.String;
+  name: Schema.Literal<E["name"]>;
+  timestamp: Schema.DateTimeUtc;
+  data: E["payload"];
+  cursor: Schema.NullOr<Schema.String>;
+}, "Type", E["payload"] extends {
+  readonly "~type.optionality": "optional";
+} ? "data" : never, E["payload"] extends {
+  readonly "~type.mutability": "mutable";
+} ? "data" : never>>;

package/dist/http/events.mjs

@@ -0,0 +1,102 @@
+import { principalOf } from "../contract/caller.mjs";
+import { Refusal } from "../contract/errors.mjs";
+import { declared } from "../contract/status.mjs";
+import { assertDistinctTags } from "../contract/declared.mjs";
+import { OccurrenceOf } from "../contract/occurrence.mjs";
+import { SubscriptionError } from "../Event.mjs";
+import { webhookSubscriber } from "../contract/webhooks.mjs";
+import { PushedOf, SubscriptionOf, queuedPush } from "../contract/push.mjs";
+import { Subscribed, WebhookCancellationOf, WebhookSubscriptionOf } from "../contract/subscribe.mjs";
+import { Effect, Schema, Stream } from "effect";
+import { HttpServerRequest } from "effect/http";
+import { HttpApiEndpoint, HttpApiSchema, OpenApi } from "effect/http-api";
+// src/http/events.ts
+/**
+* One poll's answer: the occurrences since the cursor, and when to ask again, sent as
+* `nextPollMs`, its milliseconds.
+*/
+const pageOf = (event) => Schema.Struct({
+	events: Schema.Array(OccurrenceOf(event)),
+	cursor: Schema.NullOr(Schema.String),
+	truncated: Schema.Boolean,
+	hasMore: Schema.Boolean,
+	nextPoll: Schema.DurationFromMillis
+}).pipe(Schema.encodeKeys({ nextPoll: "nextPollMs" }));
+/**
+* What a subscription's event stream sends, each as one SSE `message`: a `Checked` with the
+* position it starts from, or a `Gap` where that was no longer served, then each occurrence, a
+* `Gap` where some were missed, a `Checked` every 30 seconds, and a `Failed` where reading
+* failed and resumes. A later refusal ends it, as Effect's stream failure event.
+*/
+const sentOf = (event) => HttpApiSchema.StreamSse({
+	data: Schema.toCodecJson(PushedOf(event)),
+	error: Refusal
+});
+/** What a served subscription's event stream sends: each element's JSON, as `sentOf` encodes it. */
+const servedSent = HttpApiSchema.StreamSse({
+	data: Schema.Json,
+	error: Refusal
+});
+/**
+* The route of one event type at `path`, its poll answered as JSON and its stream as SSE, as
+* `sent` declares it.
+*/
+const eventEndpointOf = (event, path, errors, sent = sentOf(event)) => HttpApiEndpoint.post(event.name, path, {
+	payload: SubscriptionOf(event).pipe(HttpApiSchema.asJson()),
+	success: [pageOf(event), sent],
+	error: errors.map(declared)
+}).annotate(OpenApi.Description, event.description);
+/**
+* The webhook routes of one protected event type at `path`: `/subscribe`, which starts or
+* refreshes a subscription and answers its grant, and `/unsubscribe`, which ends it.
+*/
+const webhookEndpointsOf = (event, path, errors) => {
+	const withWebhooks = [...errors, SubscriptionError];
+	assertDistinctTags(`ActionHttp binding of event "${event.name}"'s webhook routes`, withWebhooks);
+	const error = withWebhooks.map(declared);
+	return [HttpApiEndpoint.post(`${event.name}/subscribe`, `${path}/subscribe`, {
+		payload: WebhookSubscriptionOf(event).pipe(HttpApiSchema.asJson()),
+		success: Subscribed,
+		error
+	}).annotate(OpenApi.Description, `Deliver ${event.name} to a webhook, or refresh its grant.`), HttpApiEndpoint.post(`${event.name}/unsubscribe`, `${path}/unsubscribe`, {
+		payload: WebhookCancellationOf(event).pipe(HttpApiSchema.asJson()),
+		success: HttpApiSchema.NoContent,
+		error
+	}).annotate(OpenApi.Description, `Stop delivering ${event.name} to a webhook.`)];
+};
+/**
+* The handlers of `feed`'s webhook routes, through `webhooks` where the host provided
+* `Webhook.layer`; without it, both fail with `Unsupported`.
+*/
+const webhookAnswers = (feed, authentication, webhooks) => {
+	const served = webhookSubscriber(feed, authentication, webhooks);
+	return {
+		subscribe: ({ payload }) => Effect.flatMap(served, ({ webhooks: service, ...subscriber }) => service.subscribe({
+			...payload,
+			...subscriber
+		})),
+		unsubscribe: ({ payload }) => Effect.flatMap(served, ({ webhooks: service, feed: subscribed, principal }) => service.unsubscribe({
+			...payload,
+			feed: subscribed,
+			principal
+		}))
+	};
+};
+/**
+* Answers a subscription's request to `feed`: a page, or, where it accepts `text/event-stream`,
+* the subscription's stream, each element its JSON. Both admit the subscriber first, so a refusal
+* is the route's error; `authentication`'s principal names a poll's subscriber, for its
+* `subscription` hook.
+*/
+const answering = (feed, authentication) => {
+	const encode = Schema.encodeEffect(Schema.toCodecJson(PushedOf(feed.event)));
+	return ({ payload: { input, cursor } }) => Effect.gen(function* () {
+		if (((yield* HttpServerRequest.HttpServerRequest).headers["accept"] ?? "").includes("text/event-stream")) {
+			const open = yield* feed.stream(input);
+			return Stream.fromQueue(yield* queuedPush(open, cursor, encode));
+		}
+		const subscriber = yield* principalOf(feed.event, authentication);
+		return yield* feed.poll(input, cursor, { subscriber });
+	});
+};
+export { answering, eventEndpointOf, pageOf, sentOf, servedSent, webhookAnswers, webhookEndpointsOf };

package/dist/http/placed.d.mts

@@ -0,0 +1,36 @@
+import { EventImplementation } from "../contract/feed.mjs";
+import { Any } from "../Event.mjs";
+import { Implementation } from "../contract/implementation.mjs";
+import { Any as Any$1 } from "../Action.mjs";
+import { AnyHttp } from "./client.mjs";
+import { HttpClient } from "effect/http";
+type Contract<H extends AnyHttp> = H["actions"][number] | H["events"][number];
+/** A call's or a subscription's decoded input, beside its contract, one of `C`. */
+/** What the contracts `C` require per request, by name: nothing. */
+type Nothing<C extends Any$1 | Any> = { readonly [K in C["name"]]: never; };
+/**
+ * What `placed` returns: an implementation of the binding's actions where it has some, and one of
+ * its event types where it has some, which require nothing.
+ */
+export type Placed<H extends AnyHttp> = ReadonlyArray<Implementation<H["actions"][number], Nothing<H["actions"][number]>, never, never> | EventImplementation<H["events"][number], Nothing<H["events"][number]>, never, never>>;
+/**
+ * The actions and event types of `binding` served where another server serves them, as a
+ * surface's implementations: each call and subscription sent on over `binding` with the client
+ * `client` answers for its decoded input and its contract, one of the binding's, carrying the
+ * caller's headers, and its answer, its errors and its occurrences passed back as they are. The
+ * surface serving them authenticates a protected one as its own and authorizes every caller; the
+ * server reached authenticates and authorizes again.
+ *
+ * **Gotchas**
+ *
+ * - The caller's credential is verified twice, by the surface serving these and by the server reached, so both are given the verifier: a credential expiring between the two is refused by the second.
+ * - The server reached builds its own verifier: one caching signing keys in memory fetches them in each of its instances, a Durable Object's again after each eviction.
+ * - Every header of the caller's request is sent on but its connection's, its body's, what it accepts and an MCP request's routing headers (`mcp-*`): one that must not reach the server reached is removed per contract by the client `client` returns, `HttpClient.mapRequest(HttpClientRequest.removeHeader("cookie"))`, which runs after them.
+ * - A header `client`'s client sets replaces the caller's of that name, as it is set after them: a service's own `authorization` is sent in place of the caller's.
+ * - A call with no HTTP request, as through `Action.client` in process or an MCP stdio surface, sends no header on: a protected one reaches the server reached with no credential, which refuses it with `Unauthenticated`.
+ * - An error the server reached declares beyond the action's own and the built-in ones, its binding's `error` or its verifier's, is a defect where it is passed back, answered as one.
+ * - A server reached that does not serve one of them, its route a 404, is a defect naming it, with the fix: a declared error whose status is 404 is passed back as it is.
+ * - A refusal of a subscription by the server reached comes after the surface admitted it, so it ends the subscription's stream where the surface's own would have answered its 401 or 403.
+ */
+export declare const placed: <const H extends AnyHttp>(binding: H, client: (input: Contract<H>["input"]["Type"], contract: Contract<H>) => HttpClient.HttpClient) => Placed<H>;
+export {};