@gjermundgaraba/effect-actions 0.19.0 → 0.21.0

package/dist/contract/pages.mjs

@@ -0,0 +1,39 @@
+import { Checked, Gap } from "./occurrence.mjs";
+import { Duration, Effect, Option, Stream } from "effect";
+// src/contract/pages.ts
+/** The shortest wait between polls, whatever a source or a server asks for. */
+const pollFloor = Duration.seconds(1);
+/** What a feed's stream yields of one read: its gap, its items, and where it ends. */
+const fedOf = ({ items, truncated, from, to }) => [
+	...truncated ? [Gap.make({ cursor: items.length === 0 ? to : from })] : [],
+	...items,
+	Checked.make({ cursor: to })
+];
+/**
+* Reads from `cursor` again and again, as long as the stream is read: what each page yields, then
+* a wait of its `nextPoll`, at least `pollFloor`, cut short by `woken`, or none where it has more;
+* where `polls` is `false`, a wait for `woken` alone.
+*/
+const pagedFrom = (read, cursor, woken, polls = true) => Stream.paginate({
+	cursor,
+	delay: Duration.zero
+}, (state) => {
+	const next = Effect.map(Effect.suspend(() => read(state.cursor)), (page) => [page.fed, Option.some({
+		cursor: page.cursor ?? state.cursor,
+		delay: page.hasMore ? Duration.zero : Duration.max(page.nextPoll, pollFloor)
+	})]);
+	const sleep = Effect.sleep(state.delay);
+	if (woken === void 0 || Duration.isZero(state.delay)) return Effect.andThen(sleep, next);
+	return Effect.andThen(polls ? Effect.race(sleep, woken) : woken, next);
+});
+/** Polls from `cursor` as `pagedFrom` reads: each page as its gap, its occurrences, its end. */
+const paged = (poll, cursor) => pagedFrom((at) => Effect.map(poll(at), (page) => ({
+	...page,
+	fed: fedOf({
+		items: page.events,
+		truncated: page.truncated,
+		from: at,
+		to: page.cursor ?? at
+	})
+})), cursor);
+export { fedOf, paged, pagedFrom };

package/dist/contract/progress.d.mts

@@ -0,0 +1,26 @@
+import { Codec } from "./codec.mjs";
+import { ErasedValue } from "./implementation.mjs";
+import { Data, Effect, Scope, Stream } from "effect";
+/** Where a call's progress goes: each value reported, checked by its schema, is given to `progress`. */
+export interface Reporting {
+  readonly progress: (value: ErasedValue) => Effect.Effect<void>;
+}
+/** The second argument of a handler of `A`, where `A` declares `progress`: what it reports by. */
+export type ReportingOf<A extends {
+  readonly progress: Codec | undefined;
+}> = A["progress"] extends undefined ? [] : [reporting: {
+  /** Reports `value` to the caller, never waiting for it: see `Action.Options.progress`. */
+  readonly progress: (value: NonNullable<A["progress"]>["Type"]) => Effect.Effect<void>;
+}];
+/** What a call of an action reporting progress `P` takes after its input. */
+export interface CallOptions<P> {
+  /**
+   * Run with each progress value the handler reports, in order, before the call answers; which
+   * values reach it, and what its failure does, are on `Action.Options.progress`.
+   */
+  readonly onProgress?: ((progress: P) => Effect.Effect<void>) | undefined;
+}
+/** What a call of `A` takes after its input, where `A` declares `progress`. */
+export type ProgressArgs<A extends {
+  readonly progress: Codec | undefined;
+}> = A["progress"] extends undefined ? [] : [options?: CallOptions<NonNullable<A["progress"]>["Type"]>];

package/dist/contract/progress.mjs

@@ -0,0 +1,72 @@
+import { Cause, Data, Effect, Exit, Fiber, Option, Queue, Schema, Stream } from "effect";
+// src/contract/progress.ts
+const capacity = 16;
+/**
+* What a handler reports by, where `progress` is declared: each value checked by the schema, one
+* breaking it a defect, and handed to `sink` from a buffer dropping the oldest, so the handler
+* never waits. Without a `sink`, values are checked and dropped.
+*/
+const buffering = (progress, sink) => {
+	const check = Schema.decodeUnknownEffect(Schema.toType(progress));
+	const checked = (value) => Effect.orDie(check(value));
+	if (sink === void 0) return Effect.succeed({
+		reporting: { progress: (value) => Effect.asVoid(checked(value)) },
+		drained: Effect.void
+	});
+	return Effect.gen(function* () {
+		const buffered = yield* Queue.sliding(capacity);
+		const forwarding = yield* Effect.forkScoped(Stream.runForEach(Stream.fromQueue(buffered), sink.progress));
+		return {
+			reporting: { progress: (value) => Effect.flatMap(checked(value), (each) => Effect.asVoid(Queue.offer(buffered, each))) },
+			drained: Effect.andThen(Queue.end(buffered), Fiber.join(forwarding))
+		};
+	});
+};
+/** Whether what is buffered still reaches the caller after `cause` ends a call. */
+const drainsAfter = (cause) => !Cause.hasInterruptsOnly(cause);
+/**
+* Runs `handle` with what it reports by, as `buffering` makes it; what is buffered when it
+* succeeds or fails reaches `sink` before its answer.
+*/
+const reportedTo = (progress, sink, handle) => {
+	if (progress === void 0) return handle(void 0);
+	return Effect.gen(function* () {
+		const { reporting, drained } = yield* buffering(progress, sink);
+		const exit = yield* Effect.exit(handle(reporting));
+		if (Exit.isSuccess(exit) || drainsAfter(exit.cause)) yield* drained;
+		return yield* exit;
+	});
+};
+/**
+* Runs the stream `handle` gives with what it reports by, as `buffering` makes it, in the
+* stream's scope; what is buffered when it ends or fails reaches `sink` before its end.
+*/
+const streamReportedTo = (progress, sink, handle) => {
+	if (progress === void 0) return handle(void 0);
+	return Stream.unwrap(Effect.map(buffering(progress, sink), ({ reporting, drained }) => handle(reporting).pipe(Stream.onEnd(drained), Stream.catchCause((cause) => drainsAfter(cause) ? Stream.unwrap(Effect.as(drained, Stream.failCause(cause))) : Stream.failCause(cause)))));
+};
+const shown = (onProgress) => (value) => Effect.catchCauseIf(Effect.suspend(() => onProgress(value)), (cause) => !Cause.hasInterruptsOnly(cause), (cause) => Effect.logWarning("onProgress failed", cause));
+/** What a caller in process hands a call for `onProgress`, as `Action.client` and the toolkit do. */
+const progressSink = (onProgress) => onProgress === void 0 ? void 0 : { progress: shown(onProgress) };
+const Progressed = Data.taggedEnum();
+const endedEarly = Effect.die(/* @__PURE__ */ new Error("An answer streamed with its progress ended without its final element"));
+/**
+* A client's answer from a call's `stream`: each `Progress` value handed to `onProgress`, where
+* the call gave one, then the `Final` value. A stream ending without one is a defect.
+*/
+const answerFrom = (stream, onProgress) => {
+	const report = progressSink(onProgress)?.progress ?? (() => Effect.void);
+	return Effect.flatMap(Stream.runFoldEffect(stream, () => Option.none(), (final, element) => Progressed.$is("Final")(element) ? Effect.succeedSome(element.value) : Effect.as(report(element.value), final)), Option.match({
+		onNone: () => endedEarly,
+		onSome: Effect.succeed
+	}));
+};
+/**
+* A client's elements from a call's `stream` of an action answering a stream: each `Progress`
+* value handed to `onProgress`, where the call gave one, and each `Element` value streamed.
+*/
+const elementsFrom = (stream, onProgress) => {
+	const report = progressSink(onProgress)?.progress ?? (() => Effect.void);
+	return Stream.flatMap(stream, (sent) => Progressed.$is("Progress")(sent) ? Stream.fromEffectDrain(report(sent.value)) : Stream.make(sent.value));
+};
+export { Progressed, answerFrom, elementsFrom, progressSink, reportedTo, streamReportedTo };

package/dist/contract/push.d.mts

@@ -0,0 +1,20 @@
+import { Codec } from "./codec.mjs";
+import "./errors.mjs";
+import { OccurrenceSchema } from "./occurrence.mjs";
+import "./pages.mjs";
+import { Any } from "../Event.mjs";
+import { Cause, Effect, Queue, Schema, Stream } from "effect";
+/** What a push subscription of `event` sends, as each surface's stream encodes it. */
+export declare const PushedOf: <E extends Any>(event: E) => 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", {}>]>;
+/**
+ * What a subscription's request carries: the event's input, and the cursor it resumes from,
+ * `null` where it is omitted.
+ */
+export declare const SubscriptionOf: <E extends Any>(event: E) => Schema.Struct<{
+  readonly input: Codec;
+  readonly cursor: Schema.withDecodingDefaultKey<Schema.NullOr<Schema.String>, never>;
+}>;

package/dist/contract/push.mjs

@@ -0,0 +1,96 @@
+import { Refusal } from "./errors.mjs";
+import { reported } from "./reported.mjs";
+import { Checked, Gap, OccurrenceOf } from "./occurrence.mjs";
+import { defaultNextPoll } from "./feed.mjs";
+import { Cause, Duration, Effect, Latch, Match, Queue, Schema, Stream } from "effect";
+// src/contract/push.ts
+/**
+* A push subscription read on through a failure no refusal explains, such as an upstream's
+* outage: its cause is logged and reported, and reading resumes from the position reached.
+*/
+const Failed = Schema.TaggedStruct("Failed", {});
+/** What a push subscription of `event` sends, as each surface's stream encodes it. */
+const PushedOf = (event) => Schema.Union([
+	OccurrenceOf(event),
+	Gap,
+	Checked,
+	Failed
+]);
+const subscriptionWith = (input) => Schema.Struct({
+	input,
+	cursor: Schema.NullOr(Schema.String).annotate({ description: "Where to resume: a cursor an occurrence or a page carried; null or omitted, from now." }).pipe(Schema.withDecodingDefaultKey(Effect.succeed(null)))
+});
+/**
+* What a subscription's request carries: the event's input, and the cursor it resumes from,
+* `null` where it is omitted.
+*/
+const SubscriptionOf = (event) => subscriptionWith(event.input);
+/** A subscription's request, its input left as JSON for its event's schema to decode. */
+const Subscription = subscriptionWith(Schema.Json);
+const queued = 16;
+const heartbeatEvery = Duration.seconds(30);
+const isFailed = Schema.is(Failed);
+/** Each element of a push stream of `surface`'s event `name` but `Failed`, which is logged. */
+const readOn = (surface, name) => (sent) => sent.pipe(Stream.mapEffect((element) => isFailed(element) ? Effect.as(Effect.logWarning(`${surface} event "${name}" failed to read, and resumes`), []) : Effect.succeed([element])), Stream.flattenIterable);
+const isRefused = Schema.is(Refusal);
+/** The refusal that `cause` fails with, unless it also holds a defect. */
+const refusalIn = (cause) => Cause.hasDies(cause) ? void 0 : cause.reasons.flatMap((reason) => Cause.isFailReason(reason) && isRefused(reason.error) ? [reason.error] : [])[0];
+/**
+* A poll of `name` that answers a failure no refusal explains, reported, as a page of none from
+* the cursor asked, read again after the poll interval: where no network carries a 500 for a
+* client to retry, as in process, it reads on as `pushed` does.
+*/
+const polledOn = (surface, name) => (poll) => (cursor) => Effect.catchCauseIf(poll(cursor), (cause) => !Cause.hasInterruptsOnly(cause) && refusalIn(cause) === void 0, (cause) => Effect.as(Effect.andThen(reported(cause), Effect.logWarning(`${surface} event "${name}" failed to read, and resumes`)), {
+	events: [],
+	cursor,
+	truncated: false,
+	hasMore: false,
+	nextPoll: defaultNextPoll
+}));
+/**
+* One push subscription of a feed `open` reads from a cursor, starting at `cursor`, each thing it
+* sends given to `deliver`. A refusal, an interruption, or, unless `resumesUnconfirmed`, a failure
+* before it is confirmed ends it; any other failure of a read or of its delivery is reported,
+* sent as `Failed`, and reading resumes from the position delivered after the poll interval.
+*/
+const pushed = (open, cursor, deliver, { resumesUnconfirmed = false, inOrder = false } = {}) => Effect.gen(function* () {
+	const confirmed = yield* Latch.make();
+	let reached = cursor;
+	let active = false;
+	let wait = Duration.zero;
+	const movedTo = (at) => Effect.suspend(() => {
+		active = true;
+		reached = at;
+		return confirmed.open;
+	});
+	const sent = (element, at) => Effect.andThen(deliver(element), movedTo(at));
+	const delivered = (fed) => Match.valueTags(fed, {
+		Gap: (gap) => sent(gap, gap.cursor),
+		Checked: (checked) => {
+			if (!active) return sent(checked, checked.cursor);
+			if (checked.cursor === null || checked.cursor === reached) return Effect.void;
+			return inOrder ? sent(checked, checked.cursor) : movedTo(checked.cursor);
+		},
+		Occurrence: (occurrence) => Effect.andThen(active ? Effect.void : sent(Checked.make({ cursor: reached }), reached), Effect.suspend(() => sent(occurrence, occurrence.cursor ?? reached)))
+	});
+	const resumes = (cause) => (active || resumesUnconfirmed) && !Cause.hasInterruptsOnly(cause) && refusalIn(cause) === void 0;
+	const waiting = Effect.sync(() => {
+		wait = defaultNextPoll;
+	});
+	const once = Stream.suspend(() => Duration.isZero(wait) ? open(reached) : Stream.unwrap(Effect.as(Effect.sleep(wait), open(reached)))).pipe(Stream.runForEach(delivered), Effect.catchCauseIf(resumes, (cause) => Effect.andThen(reported(cause), deliver(Failed.make({})))), Effect.andThen(waiting));
+	const heartbeat = Effect.andThen(confirmed.await, Effect.forever(Effect.andThen(Effect.sleep(heartbeatEvery), () => Effect.suspend(() => deliver(Checked.make({ cursor: reached }))))));
+	return yield* inOrder ? Effect.forever(once) : Effect.raceFirst(Effect.forever(once), heartbeat);
+});
+/**
+* A push subscription for a surface's streamed response: read into a bounded queue, each element
+* as `encode` gives it, forked in the current scope.
+*/
+const queuedPush = (open, cursor, encode, { ending = (run) => run, inOrder = false, capacity = queued } = {}) => Effect.gen(function* () {
+	const queue = yield* Queue.bounded(capacity);
+	yield* pushed(open, cursor, (sent) => Effect.flatMap(encode(sent), (element) => Queue.offer(queue, element)), {
+		resumesUnconfirmed: true,
+		inOrder
+	}).pipe(ending, Queue.into(queue), Effect.forkScoped({ startImmediately: true }));
+	return queue;
+});
+export { Failed, PushedOf, Subscription, SubscriptionOf, polledOn, pushed, queuedPush, readOn, refusalIn };

package/dist/contract/receiving.d.mts

@@ -0,0 +1,29 @@
+import "./errors.mjs";
+import "./pages.mjs";
+import "../Event.mjs";
+import { SigningSecret } from "./callback.mjs";
+import { Context, Effect, Schema, Scope } from "effect";
+/** A POST a receiver verified, its JSON body: an occurrence, or an envelope. */
+export interface Delivered {
+  readonly [key: string]: Schema.Json;
+}
+/**
+ * One watch's place at a receiver: the id its delivery URL names in `watchParameter`, and the
+ * secret to subscribe with.
+ */
+export interface Registered {
+  readonly id: string;
+  readonly secret: SigningSecret;
+}
+declare const Receiving_base: Context.ServiceClass<Receiving, "effect-actions/Receiving", {
+  readonly path: `/${string}`;
+  readonly register: (deliver: (body: Delivered) => boolean) => Effect.Effect<Registered, never, Scope.Scope>;
+}>;
+/**
+ * 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.
+ */
+export declare class Receiving extends Receiving_base {}
+export {};

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,11 +1,19 @@
 import { SchemaAST } from "effect";
-//#region src/contract/status.ts
+// 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;
-};
-//#endregion
-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 };