@gjermundgaraba/effect-actions 0.20.0 → 0.21.0

package/dist/cli/commands.mjs

@@ -1,14 +1,18 @@
 import { literalValues, members, unsuspended } from "../contract/ast.mjs";
 import { InvalidInput } from "../contract/errors.mjs";
-import { assertDistinct } from "../contract/names.mjs";
 import { errorSchemas } from "../contract/declared.mjs";
+import { assertDistinct } from "../contract/names.mjs";
+import { elementOf } from "../contract/stream.mjs";
+import { elementsOf } from "../contract/implementation.mjs";
 import { decodeInput } from "../contract/call.mjs";
+import { ReceivedOf } from "../contract/occurrence.mjs";
+import { SubscriptionError } from "../Event.mjs";
 import { withStderrConsole } from "../stdio/console.mjs";
 import { Console, Effect, Option, Predicate, Record, Runtime, Schema, SchemaAST, Stdio, Stream } from "effect";
 import { CliError, Command, Flag, Param } from "effect/cli";
 // src/cli/commands.ts
 const kebab = (name) => {
-	const kebabbed = name.replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2").replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/_/g, "-").replace(/^-+|-+$/g, "").toLowerCase();
+	const kebabbed = name.replaceAll(/(?<upper>[A-Z]+)(?<word>[A-Z][a-z])/gu, "$<upper>-$<word>").replaceAll(/(?<lower>[a-z0-9])(?<upper>[A-Z])/gu, "$<lower>-$<upper>").replaceAll("_", "-").replaceAll(/^-+|-+$/gu, "").toLowerCase();
 	return kebabbed === "" ? name : kebabbed;
 };
 const renderedCommandJsonFlag = Flag.Boolean("json").pipe(Flag.withDefault(false), Flag.withDescription("Print machine-readable JSON"));
@@ -20,7 +24,13 @@ const jsonKinds = [
 	"array",
 	"object"
 ];
-const jsonKindOf = (value) => value === null ? "null" : Predicate.isBoolean(value) ? "boolean" : Predicate.isNumber(value) ? "number" : Predicate.isString(value) ? "string" : Array.isArray(value) ? "array" : "object";
+const jsonKindOf = (value) => {
+	if (value === null) return "null";
+	if (Predicate.isBoolean(value)) return "boolean";
+	if (Predicate.isNumber(value)) return "number";
+	if (Predicate.isString(value)) return "string";
+	return Array.isArray(value) ? "array" : "object";
+};
 const acceptedJsonKindsOf = (ast) => members(ast).flatMap((member) => {
 	if (SchemaAST.isLiteral(member)) return [jsonKindOf(member.literal)];
 	if (SchemaAST.isEnum(member)) return member.enums.map(([, value]) => jsonKindOf(value));
@@ -51,8 +61,8 @@ const valueParam = (kind, name, field) => {
 	return Param.String(kind, name).pipe(Param.withSchema(jsonOfAcceptedKindOrText(encoded)), Param.withMetavar("value"));
 };
 const withoutOptionalAbsence = (ast) => {
-	const members = SchemaAST.isUnion(ast) ? ast.types.filter((member) => !SchemaAST.isNull(member) && !SchemaAST.isUndefined(member)) : [];
-	return members.length === 1 && members[0] !== void 0 ? members[0] : ast;
+	const present = SchemaAST.isUnion(ast) ? ast.types.filter((member) => !SchemaAST.isNull(member) && !SchemaAST.isUndefined(member)) : [];
+	return present.length === 1 && present[0] !== void 0 ? present[0] : ast;
 };
 const optionalAddedNull = (plain) => {
 	const types = members(plain);
@@ -60,7 +70,7 @@ const optionalAddedNull = (plain) => {
 };
 const repeatedElementOf = (ast) => {
 	const encoded = unsuspended(ast);
-	if (!SchemaAST.isArrays(encoded)) return void 0;
+	if (!SchemaAST.isArrays(encoded)) return;
 	const [element, ...after] = encoded.rest;
 	if (element === void 0 || after.length > 0 || !encoded.elements.every((first) => first === element) || !acceptedJsonKindsOf(element).every((kind) => kind === "string" || kind === "number")) return;
 	return {
@@ -69,26 +79,30 @@ const repeatedElementOf = (ast) => {
 	};
 };
 const noElementOccurrence = "[]";
+const namedFieldsOf = (ast) => {
+	const fields = SchemaAST.isDeclaration(ast) ? ast.typeParameters[0] : ast;
+	return new Map(fields !== void 0 && SchemaAST.isObjects(fields) ? fields.propertySignatures.map((property) => [property.name, property.type]) : []);
+};
+const elementFieldsOf = (array) => {
+	if (!SchemaAST.isArrays(array)) return;
+	const [element, ...others] = [...array.elements, ...array.rest];
+	if (element === void 0 || others.some((other) => other !== element)) return;
+	const fields = namedFieldsOf(unsuspended(element));
+	return fields.size === 0 ? void 0 : Array.from(fields, ([name, field]) => SchemaAST.isOptional(field) ? `${String(name)}?` : String(name));
+};
 const jsonHintOf = (encoded) => {
 	const value = unsuspended(encoded);
 	const kinds = new Set(acceptedJsonKindsOf(value));
-	if (kinds.size !== 1) return void 0;
+	if (kinds.size !== 1) return;
 	if (kinds.has("object")) return "A JSON object.";
-	if (!kinds.has("array")) return void 0;
+	if (!kinds.has("array")) return;
 	const fields = elementFieldsOf(value);
 	return fields === void 0 ? "A JSON array." : `A JSON array of {${fields.join(", ")}}.`;
 };
-const elementFieldsOf = (array) => {
-	if (!SchemaAST.isArrays(array)) return void 0;
-	const [element, ...others] = [...array.elements, ...array.rest];
-	if (element === void 0 || others.some((other) => other !== element)) return void 0;
-	const fields = namedFieldsOf(unsuspended(element));
-	return fields.size === 0 ? void 0 : Array.from(fields, ([name, field]) => SchemaAST.isOptional(field) ? `${String(name)}?` : String(name));
-};
 const withHint = (description, hint) => {
 	if (hint === void 0 || description === void 0) return description ?? hint;
 	const stated = description.trimEnd();
-	return /[.!?:]$/.test(stated) ? `${stated} ${hint}` : `${stated}. ${hint}`;
+	return /[.!?:]$/u.test(stated) ? `${stated} ${hint}` : `${stated}. ${hint}`;
 };
 const fieldParam = (kind, name, encoded, plain) => {
 	const optional = SchemaAST.isOptional(encoded);
@@ -97,7 +111,7 @@ const fieldParam = (kind, name, encoded, plain) => {
 	if (repeats !== void 0) {
 		const literals = stringChoicesOf(unsuspended(repeats.element));
 		const elements = literals === void 0 ? valueParam(kind, name, repeats.element) : Param.Literals(kind, name, [...literals, noElementOccurrence]);
-		const listed = (values) => Option.some(values.filter((value) => value !== noElementOccurrence));
+		const listed = (values) => Option.some(values.filter((given) => given !== noElementOccurrence));
 		return {
 			param: optional ? Param.variadic(elements).pipe(Param.map((values) => values.length === 0 ? Option.none() : listed(values))) : Param.variadic(elements, { min: repeats.min }).pipe(Param.map(listed)),
 			repeats: true,
@@ -116,13 +130,9 @@ const fieldParam = (kind, name, encoded, plain) => {
 		hint: isSwitch ? "Left out, it sends false." : jsonHintOf(encoded)
 	};
 };
-const namedFieldsOf = (ast) => {
-	const fields = SchemaAST.isDeclaration(ast) ? ast.typeParameters[0] : ast;
-	return new Map(fields !== void 0 && SchemaAST.isObjects(fields) ? fields.propertySignatures.map((property) => [property.name, property.type]) : []);
-};
 const isTransformedAsWhole = (ast) => (SchemaAST.isDeclaration(ast) ? ast.typeParameters[0] : ast)?.encoding !== void 0;
-const ownOrSuspendedDescriptionOf = (ast) => ast.context?.annotations?.description ?? SchemaAST.resolveDescription(ast) ?? describedBeforeLastCheck(ast) ?? (SchemaAST.isSuspend(ast) ? ownOrSuspendedDescriptionOf(ast.thunk()) : void 0);
 const describedBeforeLastCheck = (ast) => [ast.annotations, ...(ast.checks ?? []).map((check) => check.annotations)].map((annotations) => annotations?.["description"]).findLast(Predicate.isString);
+const ownOrSuspendedDescriptionOf = (ast) => ast.context?.annotations?.description ?? SchemaAST.resolveDescription(ast) ?? describedBeforeLastCheck(ast) ?? (SchemaAST.isSuspend(ast) ? ownOrSuspendedDescriptionOf(ast.thunk()) : void 0);
 const describedThroughAbsence = (ast) => ownOrSuspendedDescriptionOf(ast) ?? ownOrSuspendedDescriptionOf(withoutOptionalAbsence(ast));
 const describedByElement = (ast) => {
 	const array = unsuspended(withoutOptionalAbsence(ast));
@@ -191,7 +201,7 @@ var UserError = class extends CliError.UserError {
 	}
 };
 const ownStringProperty = (error, key) => {
-	if (!Predicate.hasProperty(error, key)) return void 0;
+	if (!Predicate.hasProperty(error, key)) return;
 	const value = error[key];
 	return Predicate.isString(value) ? value : void 0;
 };
@@ -228,7 +238,7 @@ const stdinTextOf = (field) => Effect.gen(function* () {
 	const stdio = yield* Effect.serviceOption(Stdio.Stdio);
 	if (Option.isNone(stdio)) return yield* Effect.die(/* @__PURE__ */ new Error("Stdio is not provided (provide NodeServices.layer, or Stdio.layerTest in a test)"));
 	if (yield* stdio.value.stdinIsTerminal) return yield* unreadableStdinField(field, `${field} is read from stdin, which is a terminal: pipe it in`);
-	return (yield* stdio.value.stdin.pipe(Stream.decodeText(), Stream.mkString, Effect.mapError((error) => unreadableStdinField(field, `stdin cannot be read: ${error.message}`)))).replace(/[\r\n]+$/, "");
+	return (yield* stdio.value.stdin.pipe(Stream.decodeText(), Stream.mkString, Effect.mapError((error) => unreadableStdinField(field, `stdin cannot be read: ${error.message}`)))).replace(/[\r\n]+$/u, "");
 });
 const inputConfig = (action, positional, aliases, stdin) => {
 	const codec = Schema.toCodecJson(action.input);
@@ -275,6 +285,24 @@ const inputConfig = (action, positional, aliases, stdin) => {
 	};
 };
 const aliasFlag = (alias) => alias.length === 1 ? `-${alias}` : `--${alias}`;
+const progressLinesOf = (progress) => {
+	if (progress === void 0) return;
+	const encode = Schema.encodeUnknownEffect(Schema.fromJsonString(Schema.toCodecJson(progress)));
+	return (value) => Effect.flatMap(Effect.orDie(encode(value)), Console.log);
+};
+const printedOf = (action) => {
+	const element = elementOf(action.success);
+	if (element === void 0) return (value, render, print) => Effect.flatMap(printedOutput(action, value, render), Option.match({
+		onNone: () => Effect.void,
+		onSome: (line) => Effect.sync(() => {
+			print(line);
+		})
+	}));
+	const encode = Schema.encodeUnknownEffect(Schema.fromJsonString(Schema.toCodecJson(element)));
+	return (value, render, print) => Stream.runForEach(elementsOf(Effect.succeed(value)), (each) => Effect.map(Effect.orDie(encode(each)), (json) => {
+		print(render === void 0 ? json : render(each));
+	}));
+};
 const command = (action, execute, options, errors) => {
 	const name = options?.name ?? kebab(action.name);
 	const description = options?.description ?? action.description;
@@ -293,7 +321,7 @@ const command = (action, execute, options, errors) => {
 			"render's --json"
 		]],
 		...Object.entries(options?.aliases ?? {}).flatMap(([field, alias]) => {
-			const bare = Predicate.isString(alias) ? alias.replace(/^-+/, "") : void 0;
+			const bare = Predicate.isString(alias) ? alias.replace(/^-+/u, "") : void 0;
 			return bare === void 0 ? [] : [[
 				bare,
 				aliasFlag(bare),
@@ -302,7 +330,7 @@ const command = (action, execute, options, errors) => {
 		})
 	], ([key]) => key, {
 		labelOf: ([, label]) => label,
-		claimantOf: ([, , claimant]) => claimant,
+		claimantOf: (claim) => claim[2],
 		fix: render === void 0 ? "rename the field or the alias" : "rename the field or the alias, or drop `render`"
 	});
 	const args = positional.map(({ param }) => param);
@@ -310,11 +338,12 @@ const command = (action, execute, options, errors) => {
 		...input,
 		...Object.fromEntries(positional.map(({ field }, index) => [field, values[index] ?? Option.none()]))
 	});
-	const run = (parsed, rendered) => decode(parsed).pipe(Effect.flatMap(execute), failing, Effect.flatMap((value) => printedOutput(action, value, rendered)), withStderrConsole, Effect.flatMap(Option.match({
-		onNone: () => Effect.void,
-		onSome: Console.log
-	})));
-	const command = render === void 0 ? Command.make(name, {
+	const progressLines = progressLinesOf(action.progress);
+	const printed = printedOf(action);
+	const run = (parsed, rendered) => Console.consoleWith((stdout) => decode(parsed).pipe(Effect.flatMap((input) => execute(input, progressLines)), Effect.flatMap((value) => printed(value, rendered, (line) => {
+		stdout.log(line);
+	})), failing, withStderrConsole));
+	const projected = render === void 0 ? Command.make(name, {
 		input: flags,
 		args
 	}, ({ input, args: values }) => run(parsedFields(input, values), void 0)) : Command.make(name, {
@@ -322,6 +351,28 @@ const command = (action, execute, options, errors) => {
 		args,
 		json: renderedCommandJsonFlag
 	}, ({ input, args: values, json }) => run(parsedFields(input, values), json ? void 0 : render));
-	return stdinHelp === void 0 ? Command.withDescription(command, description) : command.pipe(Command.withDescription(`${description}\n\n${stdinHelp}`), Command.withShortDescription(description));
+	return stdinHelp === void 0 ? Command.withDescription(projected, description) : projected.pipe(Command.withDescription(`${description}\n\n${stdinHelp}`), Command.withShortDescription(description));
+};
+/**
+* The command watching `event`, named after it, with one flag per field of its input as an
+* action's command has, and `--cursor` to resume from: it prints each occurrence and gap `watch`
+* yields as one line of compact JSON on stdout, until it is interrupted or the watch fails.
+*/
+const watchCommand = (event, watch, errors) => {
+	const { flags, decode } = inputConfig(event, [], {}, void 0);
+	const encode = Schema.encodeEffect(Schema.fromJsonString(Schema.toCodecJson(ReceivedOf(event))));
+	const failing = failingAsDerived([...errors, SubscriptionError]);
+	assertDistinct("flag", [...Object.keys(flags).map((field) => [kebab(field), `field ${field}`]), ["cursor", "--cursor"]], ([key]) => key, {
+		labelOf: ([key]) => `--${key}`,
+		claimantOf: ([, claimant]) => claimant,
+		fix: "rename the field"
+	});
+	const cursor = Flag.String("cursor").pipe(Flag.withDescription("Where to resume: a cursor an earlier line carried; omitted, from now"), Flag.optional);
+	return Command.make(event.name, {
+		input: flags,
+		cursor
+	}, ({ input, cursor: from }) => Console.consoleWith((stdout) => decode(input).pipe(Effect.flatMap((value) => Stream.runForEach(watch(value, Option.getOrUndefined(from)), (received) => Effect.flatMap(Effect.orDie(encode(received)), (line) => Effect.sync(() => {
+		stdout.log(line);
+	})))), failing, withStderrConsole))).pipe(Command.withDescription(event.description));
 };
-export { UserError, command, failingAsDerived, kebab };
+export { UserError, command, failingAsDerived, kebab, watchCommand };

package/dist/contract/ast.mjs

@@ -5,5 +5,8 @@ const members = (ast) => {
 	const resolved = unsuspended(ast);
 	return SchemaAST.isUnion(resolved) ? resolved.types.flatMap(members) : [resolved];
 };
-const literalValues = (ast) => SchemaAST.isLiteral(ast) ? [ast.literal] : SchemaAST.isEnum(ast) ? ast.enums.map(([, value]) => value) : [void 0];
+const literalValues = (ast) => {
+	if (SchemaAST.isLiteral(ast)) return [ast.literal];
+	return SchemaAST.isEnum(ast) ? ast.enums.map(([, value]) => value) : [void 0];
+};
 export { literalValues, members, unsuspended };

package/dist/contract/authorizer.d.mts

@@ -0,0 +1,8 @@
+import { Refusal } from "./errors.mjs";
+import "./implementation.mjs";
+import { Effect } from "effect";
+/** `T`, read only once it is inferred: an implementation's build channels. */
+type Deferred$1<T> = [T][T extends unknown ? 0 : never];
+/** What `implement` takes as `authorize` for contracts `C`: the rule, or an Effect building it. */
+export type Authorizer<C, RA, EAX, RAX> = ((contract: C) => Effect.Effect<void, Refusal, RA>) | Effect.Effect<(contract: C) => Effect.Effect<void, Refusal, RA>, EAX, RAX>;
+export { Deferred$1 as Deferred };

package/dist/contract/authorizer.mjs

@@ -0,0 +1,20 @@
+import { memoized } from "./implementation.mjs";
+import { Effect, Predicate } from "effect";
+// src/contract/authorizer.ts
+/**
+* The memoized authorizer of an implementation: the `authorize` given where it holds a protected
+* contract, which then requires one, and a rule allowing every call where it holds none, which
+* then takes none.
+*/
+const authorizerOf = (holding, holdsProtected, authorize) => {
+	const { singular, module } = holding;
+	if (holdsProtected && authorize === void 0) throw new Error(`Protected ${singular}s require authorize, or ${module}.allowAll`);
+	if (!holdsProtected && authorize !== void 0) throw new Error(`A public-only target takes no authorize (remove it, or list a protected ${singular})`);
+	const checked = (rule) => {
+		if (!Predicate.isFunction(rule)) throw new Error(`Missing authorize: not a function (pass your rule, ${module}.allowAll, or an Effect returning one)`);
+		return rule;
+	};
+	const given = authorize ?? (() => Effect.void);
+	return memoized(Effect.isEffect(given) ? Effect.map(given, checked) : Effect.succeed(checked(given)));
+};
+export { authorizerOf };

package/dist/contract/call.d.mts

@@ -1,11 +1,14 @@
+import "./codec.mjs";
 import "./errors.mjs";
+import { ProgressArgs } from "./progress.mjs";
 import "./implementation.mjs";
 import { Any } from "../Action.mjs";
-import { Effect, Schema } from "effect";
+import { Effect, Schema, Stream } from "effect";
 /**
- * A call of `A` answering `R`. It may leave its input out when `{}` is a valid encoded input,
- * such as for an action declared without `input` or one whose every field has a decoding
- * default, and then sends the input `{}` decodes to. Every client shares this rule:
- * `ActionHttp.client`, `ActionRpc.client`, `ActionMcp.client` and `Action.client`.
+ * A call of `A` answering `R`, taking `{ onProgress }` after its input where `A` declares
+ * `progress`. It may leave its input out when `{}` is a valid encoded input, such as for an
+ * action declared without `input` or one whose every field has a decoding default, and then
+ * sends the input `{}` decodes to. Every client shares this rule: `ActionHttp.client`,
+ * `ActionRpc.client`, `ActionMcp.client` and `Action.client`.
  */
-export type Call<A extends Any, R> = {} extends A["input"]["Encoded"] ? (...input: [] | [input: A["input"]["Type"]]) => R : (input: A["input"]["Type"]) => R;
+export type Call<A extends Any, R> = {} extends A["input"]["Encoded"] ? (...input: [] | [input: A["input"]["Type"], ...ProgressArgs<A>]) => R : (input: A["input"]["Type"], ...options: ProgressArgs<A>) => R;

package/dist/contract/call.mjs

@@ -1,6 +1,12 @@
 import { InvalidInput } from "./errors.mjs";
-import { Effect, Schema } from "effect";
+import { Effect, Predicate, Schema, Stream } from "effect";
 // src/contract/call.ts
+const isCallOptions = (options) => Predicate.hasProperty(options, "onProgress") && Predicate.isFunction(options.onProgress);
+/** The `onProgress` a call's arguments give after its input, where they give one. */
+const onProgressOf = (args) => {
+	const [, options] = args;
+	return isCallOptions(options) ? options.onProgress : void 0;
+};
 /**
 * How HTTP, RPC, MCP and a command decode a request's input: reporting every issue, and refusing a
 * field the input does not declare.
@@ -14,9 +20,45 @@ const decodeInput = (action) => {
 	const decode = Schema.decodeUnknownEffect(Schema.toCodecJson(action.input), inputParseOptions);
 	return (encoded) => Effect.mapError(decode(encoded), InvalidInput.fromSchemaError);
 };
-const inputOf = (action, args) => args.length === 0 ? Schema.decodeUnknownEffect(Schema.toCodecJson(action.input))({}) : Effect.succeed(args[0]);
-const checked = (action, send) => {
-	const encode = Schema.encodeUnknownEffect(Schema.toCodecJson(action.input), { errors: "all" });
-	return (...args) => inputOf(action, args).pipe(Effect.tap(encode), Effect.mapError(InvalidInput.fromSchemaError), Effect.flatMap(send));
+const inputOf = (action, args) => args.length === 0 ? Schema.decodeEffect(Schema.toCodecJson(action.input))({}) : Effect.succeed(args[0]);
+/**
+* Values of `schema` as they cross a network: each encoded to its JSON, then decoded back from
+* that JSON's text, which carries `-0` as `0`, every issue reported, answering the JSON sent and
+* the value received.
+*/
+const jsonRoundTrip = (schema) => {
+	const codec = Schema.toCodecJson(schema);
+	const encode = Schema.encodeUnknownEffect(codec, { errors: "all" });
+	const decode = Schema.decodeUnknownEffect(Schema.fromJsonString(codec), { errors: "all" });
+	return (value) => Effect.flatMap(encode(value), (json) => Effect.map(decode(JSON.stringify(json)), (received) => ({
+		json,
+		value: received
+	})));
+};
+/**
+* A watch's input as every client sends it: read as `inputOf` reads an action's, then through
+* its JSON, dropping undeclared fields, or `InvalidInput` reporting every issue.
+*/
+const watchInput = (event, input) => inputOf(event, input === void 0 ? [] : [input]).pipe(Effect.flatMap(jsonRoundTrip(event.input)), Effect.mapError(InvalidInput.fromSchemaError));
+/** Send the input's JSON, for a client handing it to its protocol as it is. */
+const sendingJson = (action) => Schema.encodeUnknownEffect(Schema.toCodecJson(action.input), { errors: "all" });
+/** Send the input itself once its JSON encodes, for a client encoding it by the action's schema. */
+const sendingValue = (action) => {
+	const encode = sendingJson(action);
+	return (input) => Effect.as(encode(input), input);
+};
+/**
+* A client's method of `action`, its input checked by `check` before `send` sends what the check
+* answers, with the call's `onProgress` where it gave one, taking decoded values, for `send` to
+* use where the action declares `progress`.
+*/
+const checked = (action, check, send) => {
+	const encode = check(action);
+	return (...args) => inputOf(action, args).pipe(Effect.flatMap(encode), Effect.mapError(InvalidInput.fromSchemaError), Effect.flatMap((input) => send(input, onProgressOf(args))));
+};
+/** A client's method of `action` answering a stream, its input checked as `checked` checks it. */
+const checkedStream = (action, check, send) => {
+	const method = checked(action, check, (input, onProgress) => Effect.succeed(send(input, onProgress)));
+	return (...args) => Stream.unwrap(method(...args));
 };
-export { checked, decodeInput, inputOf, inputParseOptions };
+export { checked, checkedStream, decodeInput, inputOf, inputParseOptions, jsonRoundTrip, onProgressOf, sendingJson, sendingValue, watchInput };

package/dist/contract/callback.d.mts

@@ -0,0 +1,7 @@
+import { Schema } from "effect";
+/** A Standard Webhooks signing secret: as written, `whsec_` and base64, and the key it holds. */
+export declare const SigningSecret: Schema.Struct<{
+  readonly text: Schema.String;
+  readonly key: Schema.Uint8Array;
+}>;
+export type SigningSecret = typeof SigningSecret.Type;

package/dist/contract/callback.mjs

@@ -0,0 +1,27 @@
+import { Effect, Option, Schema, SchemaIssue, SchemaTransformation } from "effect";
+// src/contract/callback.ts
+/** A webhook's callback: an https URL, which each delivery is POSTed to, decoded as a `URL`. */
+const CallbackUrl = Schema.String.annotate({ description: "The https URL each delivery is POSTed to." }).pipe(Schema.decodeTo(Schema.URL, SchemaTransformation.urlFromString), Schema.check(Schema.makeFilter((url) => url.protocol === "https:" || "an https URL")));
+/** A Standard Webhooks signing secret: as written, `whsec_` and base64, and the key it holds. */
+const SigningSecret = Schema.Struct({
+	text: Schema.String,
+	key: Schema.Uint8Array
+});
+const secretPrefix = "whsec_";
+const decodeBase64 = Schema.decodeUnknownOption(Schema.Uint8ArrayFromBase64);
+const keyOf = (text) => text.startsWith(secretPrefix) ? Option.filter(decodeBase64(text.slice(6)), (key) => key.length >= 24 && key.length <= 64) : Option.none();
+/**
+* A webhook's signing secret, as Standard Webhooks writes one: `whsec_` and the base64 of 24 to
+* 64 bytes, decoded as the `SigningSecret` it is.
+*/
+const WebhookSecret = Schema.String.annotate({ description: "whsec_ and the base64 of 24 to 64 random bytes, which signs each delivery." }).pipe(Schema.decodeTo(SigningSecret, SchemaTransformation.transformEffect({
+	decode: (text, options) => Option.match(keyOf(text), {
+		onNone: () => Effect.fail(new SchemaIssue.InvalidValue({ message: "whsec_ and the base64 of 24 to 64 random bytes" }, text, options)),
+		onSome: (key) => Effect.succeed({
+			text,
+			key
+		})
+	}),
+	encode: ({ text }) => Effect.succeed(text)
+})));
+export { CallbackUrl, SigningSecret, WebhookSecret };

package/dist/contract/caller.d.mts

@@ -1,7 +1,18 @@
-import "../Action.mjs";
+import { Codec } from "./codec.mjs";
+import { Any } from "../Action.mjs";
+import { Context, Effect } from "effect";
 /**
  * The caller of a public action, `caller: Action.Anyone`: anyone, signed in or not, and no
  * authorizer runs for it. Registered globally, so two copies of the package agree on it, as they
  * agree on a name.
  */
-export declare const Anyone: unique symbol;
+export declare const Anyone: unique symbol;
+/** What names one caller of a surface: its authentication's `principal`, where it has one. */
+export interface Keyed {
+  readonly principal?: (identity: Any["input"]["Type"]) => string;
+  readonly schema?: Codec | undefined;
+}
+/** A surface's authentication that names each caller: its `principal` given. */
+export interface Named extends Keyed {
+  readonly principal: (identity: Any["input"]["Type"]) => string;
+}

package/dist/contract/caller.mjs

@@ -1,3 +1,4 @@
+import { Context, Effect, Function } from "effect";
 // src/contract/caller.ts
 /**
 * The caller of a public action, `caller: Action.Anyone`: anyone, signed in or not, and no
@@ -5,7 +6,25 @@
 * agree on a name.
 */
 const Anyone = Symbol.for("@gjermundgaraba/effect-actions/Anyone");
-const assertAuthentication = (actions, authentication) => {
-	for (const action of actions) if (action.caller !== Anyone && (authentication === void 0 || action.caller.key !== authentication.identity.key)) throw new Error(`Protected action '${action.name}' requires its matching authentication descriptor (give it the authentication whose identity the action's caller names)`);
+/**
+* The authentication of the surface the running call came through, which names its caller where
+* it has a `principal`: none in process, as `Action.client` calls.
+*/
+const CallerKeyed = Context.Reference("effect-actions/CallerKeyed", { defaultValue: Function.constUndefined });
+/** Whether `keyed` names each caller, its `principal` given. */
+const isNamed = (keyed) => keyed?.principal !== void 0;
+/**
+* The principal of the caller of `called`, as `keyed` names it: a poll's subscriber, for its
+* `subscription` hook, and whose idempotency keys a call's are. None where `called` is public or
+* `keyed` has no `principal`: every caller is then one.
+*/
+const principalOf = (called, keyed) => keyed?.principal === void 0 || called.caller === Anyone ? Effect.undefined : Effect.map(Effect.service(called.caller), (identity) => keyed.principal?.(identity));
+const assertAuthentication = (contracts, authentication, noun = "action") => {
+	for (const contract of contracts) if (contract.caller !== Anyone && (authentication === void 0 || contract.caller.key !== authentication.identity.key)) throw new Error(`Protected ${noun} '${contract.name}' requires its matching authentication descriptor (give it the authentication whose identity the ${noun}'s caller names)`);
+};
+/** Refuses a declared `caller` that is neither `Anyone` nor an identity service. */
+const assertCaller = (caller) => {
+	if (caller !== Anyone && !Context.isKey(caller)) throw new Error("Missing caller: declare Action.Anyone or an identity service key");
+	if (caller !== Anyone && Context.isReference(caller)) throw new Error("Invalid caller: an identity is a Context.Service, not a Context.Reference");
 };
-export { Anyone, assertAuthentication };
+export { Anyone, CallerKeyed, assertAuthentication, assertCaller, isNamed, principalOf };

package/dist/contract/canonical.mjs

@@ -0,0 +1,10 @@
+import { Effect, Predicate, Schema } from "effect";
+// src/contract/canonical.ts
+/**
+* `value`, an encoded input, as JSON written one way whatever the order of its objects' keys:
+* what makes two inputs one, for a subscription's key and an idempotency key's input alike.
+*/
+const canonical = (value) => JSON.stringify(value, (_key, nested) => Predicate.isObject(nested) && !Array.isArray(nested) ? Object.fromEntries(Object.entries(nested).toSorted(([a], [b]) => a < b ? -1 : 1)) : nested);
+/** `input`, encoded to JSON by `schema`, as `canonical` writes it. */
+const canonicalInput = (schema, input) => Effect.map(Effect.orDie(Schema.encodeUnknownEffect(Schema.toCodecJson(schema))(input)), canonical);
+export { canonical, canonicalInput };

package/dist/contract/codec.d.mts

@@ -0,0 +1,9 @@
+import { Schema } from "effect";
+/** A schema a contract holds: one with no services to decode or encode. */
+export type Codec = Schema.Codec<unknown>;
+/** Struct fields, given in place of a schema. */
+export type Fields = Readonly<Record<string, Codec>>;
+/** The input of a contract declared without one: an empty object. */
+export declare const NoInput: Schema.$Record<Schema.String, Schema.Never>;
+/** The schema a contract holds for `S`, given as a schema or as struct fields. */
+export type CodecOf<S extends Codec | Fields> = S extends Codec ? S : S extends Schema.Struct.Fields ? keyof S extends never ? typeof NoInput : Extract<Schema.Struct<S>, Codec> : never;

package/dist/contract/codec.mjs

@@ -0,0 +1,9 @@
+import { Schema } from "effect";
+// src/contract/codec.ts
+/** The input of a contract declared without one: an empty object. */
+const NoInput = Schema.Record(Schema.String, Schema.Never);
+const codecOf = (schema) => {
+	if (Schema.isSchema(schema)) return schema;
+	return Reflect.ownKeys(schema).length === 0 ? NoInput : Schema.Struct(schema);
+};
+export { NoInput, codecOf };

package/dist/contract/codes.mjs

@@ -0,0 +1,81 @@
+import { Forbidden, Refusal } from "./errors.mjs";
+import { CallbackCategory, CallbackFailed, NotServed, NotSubscribed, SubscriptionError, Unsupported } from "../Event.mjs";
+import { Option, Schema, SchemaTransformation, Struct } from "effect";
+// src/contract/codes.ts
+/** The error codes SEP-3415 defines, each naming one reason. */
+const eventCodes = {
+	notFound: -32023,
+	forbidden: -32024,
+	unsupported: -32026,
+	callbackEndpoint: -32027
+};
+const sent = {
+	NotSubscribed: {
+		code: eventCodes.notFound,
+		data: Schema.Struct({ kind: Schema.Literal("subscription") }).pipe(Schema.decodeTo(Schema.instanceOf(NotSubscribed), SchemaTransformation.transform({
+			decode: () => new NotSubscribed(),
+			encode: () => ({ kind: "subscription" })
+		})))
+	},
+	NotServed: {
+		code: eventCodes.notFound,
+		data: Schema.UndefinedOr(Schema.Json).pipe(Schema.decodeTo(Schema.instanceOf(NotServed), SchemaTransformation.transform({
+			decode: () => new NotServed(),
+			encode: () => ({ kind: "event" })
+		})))
+	},
+	Unsupported: {
+		code: eventCodes.unsupported,
+		data: Schema.Struct(Struct.omit(Unsupported.fields, ["_tag"])).pipe(Schema.decodeTo(Schema.instanceOf(Unsupported), SchemaTransformation.transform({
+			decode: (fields) => new Unsupported(fields),
+			encode: ({ feature, value }) => ({
+				feature,
+				value
+			})
+		})))
+	},
+	CallbackFailed: {
+		code: eventCodes.callbackEndpoint,
+		data: Schema.Struct({ reason: CallbackCategory }).pipe(Schema.decodeTo(Schema.instanceOf(CallbackFailed), SchemaTransformation.transform({
+			decode: ({ reason }) => new CallbackFailed({ category: reason }),
+			encode: ({ category }) => ({ reason: category })
+		})))
+	}
+};
+const encodeRefusal = Schema.encodeUnknownSync(Schema.toCodecJson(Refusal));
+const decodeRefusal = Schema.decodeUnknownOption(Schema.toCodecJson(Refusal));
+/**
+* The SEP-3415 error `error` is sent as: a refusal's `-32024`, its message and the refusal as
+* its data, or its reason's code and data beside its message.
+*/
+const sentError = (error) => {
+	if (Schema.is(Refusal)(error)) return {
+		code: eventCodes.forbidden,
+		message: error.message,
+		data: encodeRefusal(error)
+	};
+	const { code, data } = sent[error.reason._tag];
+	return {
+		code,
+		message: error.message,
+		data: Schema.encodeUnknownSync(Schema.toCodecJson(data))(error.reason)
+	};
+};
+/**
+* The refusal a SEP-3415 error carries, as `sentError` writes one: its `data` decoded, or
+* `Forbidden` with its message where `data` is no refusal.
+*/
+const refusalOf = (error) => Option.getOrElse(decodeRefusal(error.data), () => new Forbidden({ message: error.message }));
+/**
+* What a SEP-3415 error of the event `name` names, as a subscription's request fails with one and
+* its termination carries one: a reason of `Event.SubscriptionError`, or the refusal; `undefined`
+* for a code SEP-3415 does not define, or one whose `data` does not say what it names.
+*/
+const reasonOf = (name, error) => {
+	if (error.code === eventCodes.forbidden) return refusalOf(error);
+	for (const { code, data } of Object.values(sent)) {
+		const reason = code === error.code ? Schema.decodeUnknownOption(data)(error.data) : Option.none();
+		if (Option.isSome(reason)) return SubscriptionError.of(name, reason.value);
+	}
+};
+export { eventCodes, reasonOf, refusalOf, sentError };

package/dist/contract/declared.mjs

@@ -1,13 +1,19 @@
-import { literalValues, members } from "./ast.mjs";
 import { Anyone, assertAuthentication } from "./caller.mjs";
+import { literalValues, members } from "./ast.mjs";
 import { builtIns } from "./errors.mjs";
-import { assertOnce } from "./names.mjs";
 import { httpApiStatusOf } from "./status.mjs";
 import { Predicate, Schema, SchemaAST } from "effect";
 // src/contract/declared.ts
-const errorList = (error) => error === void 0 ? [] : Schema.isSchema(error) ? [error] : error;
+const errorList = (error) => {
+	if (error === void 0) return [];
+	return Schema.isSchema(error) ? [error] : error;
+};
 const ownsNothing = (ast) => httpApiStatusOf(ast) === void 0 && ast.checks === void 0 && ast.encoding === void 0;
-const schemasOf = (ast) => !ownsNothing(ast) ? [ast] : SchemaAST.isSuspend(ast) ? schemasOf(ast.thunk()) : SchemaAST.isUnion(ast) ? ast.types.flatMap(schemasOf) : [ast];
+const schemasOf = (ast) => {
+	if (!ownsNothing(ast)) return [ast];
+	if (SchemaAST.isSuspend(ast)) return schemasOf(ast.thunk());
+	return SchemaAST.isUnion(ast) ? ast.types.flatMap(schemasOf) : [ast];
+};
 /** `errors` as the schemas a call decodes a failure with, in order, each once. */
 const errorSchemas = (errors) => {
 	const schemas = /* @__PURE__ */ new Map();
@@ -24,6 +30,14 @@ const projectedErrors = (action, surface = []) => errorSchemas([
 * binding's and, where `action` is protected, its authentication's.
 */
 const bindingErrors = (action, binding) => projectedErrors(action, action.caller === Anyone || binding.authentication === void 0 ? binding.error : [...binding.error, ...binding.authentication.error]);
+/**
+* Every error a binding's subscription to `event` declares: the built-in ones, the binding's and,
+* where `event` is protected, its authentication's. An event type declares none of its own.
+*/
+const eventErrors = (event, binding) => bindingErrors({
+	error: [],
+	caller: event.caller
+}, binding);
 const encodedTags = (ast) => members(SchemaAST.toEncoded(ast)).flatMap((member) => {
 	const tag = SchemaAST.isObjects(member) ? member.propertySignatures.find((property) => property.name === "_tag")?.type : void 0;
 	return tag === void 0 ? [] : members(tag).flatMap(literalValues).filter(Predicate.isString);
@@ -38,17 +52,19 @@ const assertDistinctTags = (what, errors) => {
 	}
 };
 /**
-* The checks `ActionHttp.make` and `ActionRpc.make` share: each action once, the descriptor every
-* protected action names, and each call's errors distinct by `_tag`. Returns the binding's `error`, as a list, and `authentication`.
+* The checks `ActionHttp.make` and `ActionRpc.make` share: the descriptor every protected action
+* and event type names, and each call's and each subscription's errors distinct by `_tag`.
+* Returns the binding's `error`, as a list, and `authentication`.
 */
-const bindingOf = (what, actions, options) => {
-	assertOnce("action", actions);
+const bindingOf = (what, actions, events, options) => {
 	const bound = {
 		error: errorList(options.error),
 		authentication: options.authentication
 	};
 	assertAuthentication(actions, bound.authentication);
+	assertAuthentication(events, bound.authentication, "event");
 	for (const action of actions) assertDistinctTags(`${what} of "${action.name}"`, bindingErrors(action, bound));
+	for (const event of events) assertDistinctTags(`${what} of event "${event.name}"`, eventErrors(event, bound));
 	return bound;
 };
-export { assertDistinctTags, bindingErrors, bindingOf, errorList, errorSchemas, projectedErrors };
+export { assertDistinctTags, bindingErrors, bindingOf, errorList, errorSchemas, eventErrors, projectedErrors };

package/dist/contract/digest.mjs

@@ -0,0 +1,6 @@
+import { Effect } from "effect";
+// src/contract/digest.ts
+const encoder = new TextEncoder();
+/** The SHA-256 of `text`, in hex. */
+const sha256Hex = (text) => Effect.promise(async () => Array.from(new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(text))), (byte) => byte.toString(16).padStart(2, "0")).join(""));
+export { sha256Hex };