@gjermundgaraba/effect-actions 0.20.0 → 0.21.0

package/dist/contract/receiving.mjs

@@ -0,0 +1,42 @@
+import { Forbidden } from "./errors.mjs";
+import { Gap, untaggedOccurrenceOf } from "./occurrence.mjs";
+import { reasonOf, refusalOf } from "./codes.mjs";
+import { Context, Effect, Option, Schema, Struct } from "effect";
+// src/contract/receiving.ts
+/** The query parameter of a watch's delivery URL naming its place at the receiver. */
+const watchParameter = "watch";
+/**
+* Where a watch by webhook receives its deliveries in this process: `Webhook.layerReceiver`
+* provides it beside its route at `path`, and `register` keeps a watch's place for its scope,
+* handing each verified body to `deliver`, which answers `false` while the watch has no room
+* for it.
+*/
+var Receiving = class extends Context.Service()("effect-actions/Receiving") {};
+const Terminated = Schema.Struct({ error: Schema.Struct({
+	code: Schema.optional(Schema.Int),
+	message: Schema.String,
+	data: Schema.optional(Schema.Json)
+}) });
+const decodeTerminated = Schema.decodeUnknownOption(Terminated);
+const decodeGap = Schema.decodeUnknownEffect(Schema.toCodecJson(Gap.mapFields(Struct.omit(["_tag"]))));
+const ended = new Forbidden({ message: "The subscription was ended." });
+/**
+* What a watch of `event` reads from one delivered body: its occurrence, or the gap an envelope
+* reports; a `terminated` envelope fails with the reason its error's code names, its refusal for
+* any other, an envelope of another type is skipped, and a body that does not decode fails with a
+* `SchemaError`.
+*/
+const webhookFed = (event) => {
+	const occurrenceOf = untaggedOccurrenceOf(event);
+	return (body) => {
+		const { type } = body;
+		if (type === void 0) return Effect.map(occurrenceOf(body), (occurrence) => [occurrence]);
+		if (type === "gap") return Effect.map(decodeGap(body), (fields) => [Gap.make(fields)]);
+		if (type === "terminated") return Effect.fail(Option.match(decodeTerminated(body), {
+			onNone: () => ended,
+			onSome: ({ error }) => reasonOf(event.name, error) ?? refusalOf(error)
+		}));
+		return Effect.succeed([]);
+	};
+};
+export { Receiving, watchParameter, webhookFed };

package/dist/contract/recent.mjs

@@ -0,0 +1,12 @@
+// src/contract/recent.ts
+const makeRecent = (size) => {
+	const ids = /* @__PURE__ */ new Set();
+	return {
+		has: (id) => ids.has(id),
+		add: (id) => {
+			ids.add(id);
+			if (ids.size > size) ids.delete(ids.values().next().value ?? id);
+		}
+	};
+};
+export { makeRecent };

package/dist/contract/reported.mjs

@@ -0,0 +1,16 @@
+import { Effect, ErrorReporter } from "effect";
+// src/contract/reported.ts
+/** Logs `cause` and gives it to the request's `ErrorReporter`s, as a failed call's is. */
+const reported = (cause) => Effect.andThen(Effect.logError(cause), ErrorReporter.report(cause));
+var InternalError = class extends Error {
+	[ErrorReporter.ignore] = true;
+	constructor() {
+		super("Internal server error");
+	}
+};
+/**
+* `cause` `reported`, then a defect that says no more than "Internal server error", reported no
+* further: what a surface sends where it would otherwise encode a defect's details.
+*/
+const concealed = (cause) => Effect.andThen(reported(cause), Effect.die(new InternalError()));
+export { concealed, reported };

package/dist/contract/serving.mjs

@@ -0,0 +1,63 @@
+import { Anyone, assertAuthentication } from "./caller.mjs";
+import { assertDistinct, assertOnce, heldOnce } from "./names.mjs";
+import { Implementation, assertHeld, markingOthers, notHeld, provideBuilders, select, servedBy, toList } from "./implementation.mjs";
+import { eventsOf, feedBuilders, selectEvents } from "./feed.mjs";
+import { selection } from "./listed.mjs";
+// src/contract/serving.ts
+/**
+* What a surface without a binding serves of `served`: the actions and event types `actions`
+* lists, each implementation holding those alone, or every one where it lists none.
+*/
+const selectFrom = (served, actions) => {
+	const listed = selection(actions);
+	return {
+		apps: select(toList(served), listed.actions),
+		events: selectEvents(eventsOf(served), listed.events)
+	};
+};
+/**
+* The event implementations among `served` a binding of `bound` serves, each holding the served
+* event types alone: those `listed` lists, or else every bound one, refusing implementations none
+* of whose event types it binds, as `servedBy` refuses such action implementations.
+*/
+const eventsServedBy = (what, bound, served, listed) => {
+	const apps = eventsOf(served);
+	if (listed !== void 0) assertHeld(notHeld.byBinding, listed, bound);
+	const unbound = apps.filter((app) => !app.events.some((event) => bound.includes(event)));
+	if (listed === void 0 && unbound.length > 0 && unbound.length === apps.length) {
+		const names = new Set(bound.map(({ name }) => name));
+		throw new Error(`No event of these implementations is in this ${what}: ${markingOthers(unbound.flatMap((app) => app.events), names)} (pass an implementation of a bound event, or bind one of these)`);
+	}
+	const held = new Set(apps.flatMap((app) => app.events));
+	const selected = selectEvents(apps, listed ?? bound.filter((event) => held.has(event)));
+	assertOnce("served event", selected.flatMap((app) => app.events), heldOnce);
+	return selected;
+};
+/**
+* What `ActionHttp.layer` and `ActionRpc.layer` serve, with the checks they share: the actions
+* and event types `options.actions` lists, or every one of the binding's the implementations
+* hold; `authentication` is the binding's where a served contract is protected.
+*/
+const servingOf = (what, binding, served, options) => {
+	const listed = selection(options.actions);
+	const apps = servedBy(what, binding.actions, toList(served), listed.actions);
+	const actions = apps.flatMap((app) => app.actions);
+	const events = eventsServedBy(what, binding.events, served, listed.events);
+	const eventTypes = events.flatMap((app) => app.events);
+	assertAuthentication(actions, binding.authentication);
+	assertAuthentication(eventTypes, binding.authentication, "event");
+	assertDistinct("middleware", options.middleware ?? [], (key) => key.key, { fix: "list each middleware once" });
+	return {
+		apps,
+		actions,
+		events,
+		eventTypes,
+		authentication: [...actions, ...eventTypes].some((contract) => contract.caller !== Anyone) ? binding.authentication : void 0
+	};
+};
+/**
+* Provide the builders of what `servingOf` selects, the action implementations' and the event
+* implementations', to a surface's layer.
+*/
+const provideServed = (served) => provideBuilders([...served.apps.map((app) => Implementation.layerOf(app)), ...feedBuilders(served.events)]);
+export { provideServed, selectFrom, servingOf };

package/dist/contract/status.mjs

@@ -1,10 +1,19 @@
 import { SchemaAST } from "effect";
 // src/contract/status.ts
 const httpApiStatusOf = SchemaAST.resolveAt("httpApiStatus");
+const transientStatuses = /* @__PURE__ */ new Set([
+	408,
+	429,
+	500,
+	502,
+	503,
+	504
+]);
+/** Whether a server answering `status` may answer otherwise once it recovers. */
+const isTransientStatus = (status) => transientStatuses.has(status);
 const statusThroughSuspensions = (ast) => httpApiStatusOf(ast) ?? (SchemaAST.isSuspend(ast) ? statusThroughSuspensions(ast.thunk()) : void 0);
+/** The status an endpoint answers `error` with: its own, through suspensions, 422 without one. */
+const declaredStatus = (error) => statusThroughSuspensions(error.ast) ?? 422;
 /** One error schema, from `errorSchemas`, as an endpoint declares it: with its status, 422 without one. */
-const declared = (error) => {
-	const status = statusThroughSuspensions(error.ast);
-	return status === void 0 ? error.annotate({ httpApiStatus: 422 }) : httpApiStatusOf(error.ast) === void 0 ? error.annotate({ httpApiStatus: status }) : error;
-};
-export { declared, httpApiStatusOf };
+const declared = (error) => httpApiStatusOf(error.ast) === void 0 ? error.annotate({ httpApiStatus: declaredStatus(error) }) : error;
+export { declared, declaredStatus, httpApiStatusOf, isTransientStatus };

package/dist/contract/stream.d.mts

@@ -0,0 +1,34 @@
+import { Codec, CodecOf, Fields } from "./codec.mjs";
+import { Effect, Schema, Stream } from "effect";
+declare const TypeId = "~effect-actions/Stream";
+/** The success of an action answering a stream: a schema of `Stream`s, holding its element's. */
+export interface StreamOf<Element extends Codec> extends Schema.declare<Stream.Stream<Element["Type"]>> {
+  readonly Rebuild: StreamOf<Element>;
+  readonly [TypeId]: typeof TypeId;
+  /** The schema of each element. */
+  readonly element: Element;
+}
+/**
+ * A success that is a stream of `element`, a schema or struct fields: the handler returns a
+ * `Stream` of them, which may fail with the action's errors, and every client's call returns
+ * one. How each surface carries it is on `ActionHttp.layer`, `ActionRpc.make`,
+ * `ActionMcp.layerHttp`, `ActionToolkit.make` and `ActionCli.command`.
+ * Guide: `docs/Action-streams.md` in this package; in an application: build-events' `tailLog`.
+ *
+ * **Gotchas**
+ *
+ * - A tool answers one result, so MCP and a toolkit collect the whole stream before they answer, its elements as one array: a stream that never ends never answers there.
+ * - An element breaking its schema is the call's defect, as an answer breaking `success` is.
+ * - With `progress`, values and elements are each in their order, not against each other: a value may reach `onProgress` after an element yielded after it.
+ */
+declare const Stream$1: <const E extends Codec | Fields>(element: E) => StreamOf<CodecOf<E>>;
+/** What a handler or a call of an action with success `S` answers: a stream, or one value. */
+export type Answer<S extends Codec, E, R> = [S] extends [never] ? Effect.Effect<never, E, R> : [S] extends [StreamOf<infer Element>] ? Stream.Stream<Element["Type"], E, R> : Effect.Effect<S["Type"], E, R>;
+/**
+ * The success a tool answers for an action with success `S`: an array of the elements of one
+ * answering a stream, collected whole, or `S`.
+ */
+export type ToolSuccess<S extends Codec> = [S] extends [StreamOf<infer Element>] ? Schema.$Array<Element> : S;
+/** What a call of an action with success `S` gives one at a time: an element, or its answer. */
+export type Each<S extends Codec> = [S] extends [StreamOf<infer Element>] ? Element["Type"] : S["Type"];
+export { Stream$1 as Stream };

package/dist/contract/stream.mjs

@@ -0,0 +1,31 @@
+import { codecOf } from "./codec.mjs";
+import { Predicate, Schema, Stream } from "effect";
+// src/contract/stream.ts
+const TypeId = "~effect-actions/Stream";
+const streams = Schema.declare(Stream.isStream);
+/**
+* A success that is a stream of `element`, a schema or struct fields: the handler returns a
+* `Stream` of them, which may fail with the action's errors, and every client's call returns
+* one. How each surface carries it is on `ActionHttp.layer`, `ActionRpc.make`,
+* `ActionMcp.layerHttp`, `ActionToolkit.make` and `ActionCli.command`.
+* Guide: `docs/Action-streams.md` in this package; in an application: build-events' `tailLog`.
+*
+* **Gotchas**
+*
+* - A tool answers one result, so MCP and a toolkit collect the whole stream before they answer, its elements as one array: a stream that never ends never answers there.
+* - An element breaking its schema is the call's defect, as an answer breaking `success` is.
+* - With `progress`, values and elements are each in their order, not against each other: a value may reach `onProgress` after an element yielded after it.
+*/
+const Stream$1 = (element) => Schema.make(streams.ast, {
+	[TypeId]: TypeId,
+	element: codecOf(element)
+});
+const isStreamOf = (success) => Predicate.hasProperty(success, TypeId);
+/** The element schema of an action answering a stream, `undefined` for any other action. */
+const elementOf = (success) => isStreamOf(success) ? success.element : void 0;
+/** The success a tool answers for an action with `success`, as `ToolSuccess` types it. */
+const toolSuccessOf = (success) => {
+	const element = elementOf(success);
+	return element === void 0 ? success : Schema.Array(element);
+};
+export { Stream$1 as Stream, elementOf, toolSuccessOf };

package/dist/contract/subscribe.d.mts

@@ -0,0 +1,45 @@
+import { Codec } from "./codec.mjs";
+import { Any } from "../Event.mjs";
+import { Schema } from "effect";
+/** What a webhook subscribe to `event` takes: a subscription's input and cursor, and its fields. */
+export declare const WebhookSubscriptionOf: <E extends Any>(event: E) => Schema.Struct<{
+  readonly input: Codec;
+  readonly cursor: Schema.withDecodingDefaultKey<Schema.NullOr<Schema.String>, never>;
+  delivery: Schema.Struct<{
+    readonly url: Schema.decodeTo<Schema.URL, Schema.String, never, never>;
+    readonly secret: Schema.decodeTo<Schema.Struct<{
+      readonly text: Schema.String;
+      readonly key: Schema.Uint8Array;
+    }>, Schema.String, never, never>;
+  }>;
+  ttlMs: Schema.optional<Schema.NullOr<Schema.Finite>>;
+}>;
+/** A webhook subscribe's request, its input decoded, as a surface reads it whatever its event. */
+export type AnyWebhookSubscription = ReturnType<typeof WebhookSubscriptionOf<Any>>["Type"];
+/** What a webhook unsubscribe from `event` takes: the input and callback it subscribed with. */
+export declare const WebhookCancellationOf: <E extends Any>(event: E) => Schema.Struct<{
+  readonly input: Codec;
+  readonly delivery: Schema.Struct<{
+    readonly url: Schema.decodeTo<Schema.URL, Schema.String, never, never>;
+  }>;
+}>;
+/** A webhook unsubscribe's request, its input decoded, whatever its event. */
+export type AnyWebhookCancellation = ReturnType<typeof WebhookCancellationOf<Any>>["Type"];
+/**
+ * A webhook subscription's grant: its id, which each delivery's `X-MCP-Subscription-Id` carries,
+ * when to refresh it by, the position it is safe to resume from, and whether delivery starts
+ * later than the cursor asked.
+ */
+export declare const Subscribed: Schema.Struct<{
+  readonly id: Schema.String;
+  readonly refreshBefore: Schema.NullOr<Schema.String>;
+  readonly cursor: Schema.NullOr<Schema.String>;
+  readonly truncated: Schema.Boolean;
+  readonly deliveryStatus: Schema.optional<Schema.Struct<{
+    readonly active: Schema.Boolean;
+    readonly lastDeliveryAt: Schema.NullOr<Schema.String>;
+    readonly lastError: Schema.NullOr<Schema.Literals<readonly ["connection_refused", "timeout", "tls_error", "http_4xx", "http_5xx", "challenge_failed"]>>;
+    readonly failedSince: Schema.optional<Schema.String>;
+  }>>;
+}>;
+export type Subscribed = typeof Subscribed.Type;

package/dist/contract/subscribe.mjs

@@ -0,0 +1,50 @@
+import { CallbackCategory } from "../Event.mjs";
+import { CallbackUrl, WebhookSecret } from "./callback.mjs";
+import { SubscriptionOf } from "./push.mjs";
+import { Schema, Struct } from "effect";
+// src/contract/subscribe.ts
+/** Where a webhook subscription delivers: its callback, and the secret signing each POST. */
+const WebhookCallback = Schema.Struct({
+	url: CallbackUrl,
+	secret: WebhookSecret
+});
+/** The callback a webhook unsubscribe names: its URL alone. */
+const WebhookTarget = WebhookCallback.mapFields(Struct.pick(["url"]));
+/**
+* What a webhook subscribe asks beside the subscription it names: its callback, and the lifetime
+* it suggests in milliseconds, `null` asking for none.
+*/
+const webhookFields = {
+	delivery: WebhookCallback,
+	ttlMs: Schema.optional(Schema.NullOr(Schema.Finite)).annotate({ description: "The lifetime it suggests, in milliseconds; the answer's refreshBefore is the grant." })
+};
+/** What a webhook subscribe to `event` takes: a subscription's input and cursor, and its fields. */
+const WebhookSubscriptionOf = (event) => SubscriptionOf(event).pipe(Schema.fieldsAssign(webhookFields));
+/** What a webhook unsubscribe from `event` takes: the input and callback it subscribed with. */
+const WebhookCancellationOf = (event) => Schema.Struct({
+	input: event.input,
+	delivery: WebhookTarget
+});
+/**
+* How a webhook subscription's deliveries are going, as a refresh answers it: whether it is
+* delivering, when it last delivered, and the category of its last failure, since when it fails.
+*/
+const DeliveryStatus = Schema.Struct({
+	active: Schema.Boolean,
+	lastDeliveryAt: Schema.NullOr(Schema.String),
+	lastError: Schema.NullOr(CallbackCategory),
+	failedSince: Schema.optional(Schema.String)
+});
+/**
+* A webhook subscription's grant: its id, which each delivery's `X-MCP-Subscription-Id` carries,
+* when to refresh it by, the position it is safe to resume from, and whether delivery starts
+* later than the cursor asked.
+*/
+const Subscribed = Schema.Struct({
+	id: Schema.String,
+	refreshBefore: Schema.NullOr(Schema.String),
+	cursor: Schema.NullOr(Schema.String),
+	truncated: Schema.Boolean,
+	deliveryStatus: Schema.optional(DeliveryStatus)
+});
+export { DeliveryStatus, Subscribed, WebhookCallback, WebhookCancellationOf, WebhookSubscriptionOf, WebhookTarget, webhookFields };

package/dist/contract/transient.mjs

@@ -0,0 +1,28 @@
+import { isTransientStatus } from "./status.mjs";
+import { readOn } from "./push.mjs";
+import { Cause, Duration, Effect, Function, Match, Predicate, Stream } from "effect";
+import { HttpClientError } from "effect/http";
+// src/contract/transient.ts
+/** The status a server answered with, where `error` is a failure to read its answer. */
+const answeredStatus = ({ reason }) => Match.value(reason).pipe(Match.tag("StatusCodeError", "DecodeError", ({ response }) => response.status), Match.orElse(Function.constUndefined));
+/** Whether an HTTP client's failure, by its `reason`, is one a reconnect may outlast. */
+const isTransientReason = (reason) => Match.value(reason).pipe(Match.tag("TransportError", () => true), Match.tag("DecodeError", ({ response }) => response.status < 300 || isTransientStatus(response.status)), Match.tag("StatusCodeError", ({ response }) => isTransientStatus(response.status)), Match.orElse(() => false));
+/** Whether a remote watch's failure is one a reconnect may outlast. */
+const isTransient = Predicate.or(Cause.isTimeoutError, Predicate.compose(HttpClientError.isHttpClientError, ({ reason }) => isTransientReason(reason)));
+const silentFor = Duration.seconds(60);
+/**
+* `request`, failing with a `TimeoutError`, which `isTransient` admits, when it is unanswered for
+* as long as a stream may be silent, such as a server that holds its status back.
+*/
+const failingWhenUnanswered = (request) => Effect.timeout(request, silentFor);
+/** `stream`, failing with a `TimeoutError`, which `isTransient` admits, once it goes silent. */
+const failingWhenSilent = (stream) => stream.pipe(Stream.timeoutOrElse({
+	duration: silentFor,
+	orElse: () => Stream.fail(new Cause.TimeoutError("The event stream went silent"))
+}));
+/**
+* What a client reads from a push stream of `surface`'s event `name`: each element but `Failed`,
+* which is logged, the server having read on; failing with a `TimeoutError` once it goes silent.
+*/
+const receivedFrom = (surface, name) => (sent) => sent.pipe(failingWhenSilent, readOn(surface, name));
+export { answeredStatus, failingWhenSilent, failingWhenUnanswered, isTransient, isTransientReason, receivedFrom };

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 };