@smthrs/notifications 0.0.0-stage → 1.0.0-rc.12

package/dist/cjs/layerWebhook.js

@@ -0,0 +1,145 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var layerWebhook_exports = {};
+__export(layerWebhook_exports, {
+  defaultWebhookTimeout: () => defaultWebhookTimeout,
+  layerWebhook: () => layerWebhook
+});
+module.exports = __toCommonJS(layerWebhook_exports);
+var import_effect = require("effect");
+var FetchHttpClient = __toESM(require("effect/http/FetchHttpClient"), 1);
+var Headers = __toESM(require("effect/http/Headers"), 1);
+var HttpClient = __toESM(require("effect/http/HttpClient"), 1);
+var HttpClientRequest = __toESM(require("effect/http/HttpClientRequest"), 1);
+var import_AlertPolicy = require("./AlertPolicy.js");
+var import_AlertSink = require("./AlertSink.js");
+const defaultWebhookTimeout = import_effect.Duration.seconds(10);
+const webhookUrl = (raw) => import_effect.Effect.suspend(() => {
+  const misconfigured = new import_AlertSink.AlertError({
+    code: "sink_misconfigured",
+    message: "Alert webhook url must be an absolute http: or https: URL"
+  });
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    return import_effect.Effect.fail(misconfigured);
+  }
+  return parsed.protocol === "http:" || parsed.protocol === "https:" ? import_effect.Effect.succeed(raw) : import_effect.Effect.fail(misconfigured);
+});
+const followingNoRedirects = (effect) => import_effect.Effect.flatMap(
+  import_effect.Effect.serviceOption(FetchHttpClient.RequestInit),
+  (init) => import_effect.Effect.provideService(effect, FetchHttpClient.RequestInit, {
+    ...import_effect.Option.isSome(init) ? init.value : {},
+    redirect: "manual"
+  })
+);
+const rejected = (status) => new import_AlertSink.AlertError({ code: "sink_rejected", status, message: `Alert webhook answered ${status}` });
+const originAttributes = /* @__PURE__ */ new Set([
+  "http.request.method",
+  "url.scheme",
+  "server.address",
+  "server.port",
+  "http.response.status_code",
+  "error.type"
+]);
+const isHeaderAttribute = (key) => key.startsWith("http.request.header.") || key.startsWith("http.response.header.");
+const redirectHeaderNames = ["location", "content-location"];
+const withoutRequest = (tracer) => import_effect.Tracer.make({
+  ...tracer,
+  span(options) {
+    const span = tracer.span(options);
+    const end = span.end.bind(span);
+    const attribute = span.attribute.bind(span);
+    span.attribute = (key, value) => {
+      if (originAttributes.has(key) || isHeaderAttribute(key)) attribute(key, value);
+    };
+    span.end = (endTime, exit) => {
+      if (exit._tag === "Success") return end(endTime, import_effect.Exit.void);
+      if (import_effect.Cause.hasInterruptsOnly(exit.cause)) return end(endTime, exit);
+      const status = span.attributes.get("http.response.status_code");
+      return end(
+        endTime,
+        import_effect.Exit.fail(
+          typeof status === "number" ? rejected(status) : new import_AlertSink.AlertError({ code: "sink_unreachable", message: "Alert webhook could not be reached" })
+        )
+      );
+    };
+    return span;
+  }
+});
+const layerWebhook = (options) => import_effect.Layer.effect(
+  import_AlertSink.Sink,
+  import_effect.Effect.gen(function* () {
+    const url = yield* import_effect.Effect.orDie(webhookUrl(options.url));
+    const client = HttpClient.withScope(yield* HttpClient.HttpClient);
+    const timeout = options.timeout ?? defaultWebhookTimeout;
+    const redactedNames = [
+      ...Object.keys(options.headers ?? {}).map((name) => name.toLowerCase()),
+      ...redirectHeaderNames
+    ];
+    return {
+      deliver: (alert) => client.execute(
+        HttpClientRequest.post(url).pipe(
+          (request) => options.headers === void 0 ? request : HttpClientRequest.setHeaders(request, options.headers),
+          HttpClientRequest.setHeader("Idempotency-Key", (0, import_AlertPolicy.alertId)(alert)),
+          HttpClientRequest.bodyJsonUnsafe({ ...alert, alertId: (0, import_AlertPolicy.alertId)(alert) })
+        )
+      ).pipe(
+        followingNoRedirects,
+        import_effect.Effect.updateService(Headers.CurrentRedactedNames, (names) => [...names, ...redactedNames]),
+        // A host may name HTTP spans for their url. This one is named for
+        // its method, as the client names it by default.
+        import_effect.Effect.provideService(HttpClient.SpanNameGenerator, (request) => request.method),
+        import_effect.Effect.updateService(import_effect.Tracer.Tracer, withoutRequest),
+        import_effect.Effect.flatMap(
+          (response) => response.status >= 200 && response.status < 300 ? import_effect.Effect.void : import_effect.Effect.fail(rejected(response.status))
+        ),
+        import_effect.Effect.timeout(timeout),
+        import_effect.Effect.scoped,
+        import_effect.Effect.catchTag("TimeoutError", () => import_effect.Effect.fail(
+          new import_AlertSink.AlertError({
+            code: "sink_timeout",
+            message: `Alert webhook did not answer within ${import_effect.Duration.toMillis(timeout)} ms`
+          })
+        )),
+        // The transport error holds the request, and the request holds the
+        // caller's headers. Only its reason tag crosses into the failure.
+        import_effect.Effect.catchTag("HttpClientError", (cause) => import_effect.Effect.fail(
+          new import_AlertSink.AlertError({
+            code: "sink_unreachable",
+            reason: cause.reason._tag,
+            message: "Alert webhook could not be reached"
+          })
+        ))
+      )
+    };
+  })
+).pipe(import_effect.Layer.provide(FetchHttpClient.layer));
+//# sourceMappingURL=layerWebhook.js.map

package/dist/cjs/layerWebhook.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/layerWebhook.ts"],
+  "sourcesContent": ["/**\n * The webhook alert sink: one POST per alert, keyed so the receiver can\n * dedupe on it.\n *\n * The transport rules live here rather than beside the policy, because which\n * endpoint is paged, over which scheme, carrying which credential is a\n * deployment's decision and the delays are not.\n *\n * @since 1.0.0\n */\n\nimport { Cause, Duration, Effect, Exit, Layer, Option, Tracer } from \"effect\"\nimport * as FetchHttpClient from \"effect/http/FetchHttpClient\"\nimport * as Headers from \"effect/http/Headers\"\nimport * as HttpClient from \"effect/http/HttpClient\"\nimport * as HttpClientRequest from \"effect/http/HttpClientRequest\"\nimport { alertId } from \"./AlertPolicy.ts\"\nimport { AlertError, Sink } from \"./AlertSink.ts\"\n\n/**\n * How long the webhook sink waits for an answer before it calls the page\n * refused.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const defaultWebhookTimeout: Duration.Duration = Duration.seconds(10)\n\n/**\n * The one check the webhook endpoint gets before an alert is ever built on\n * it.\n *\n * The url is operator config rather than runtime input, so there is no SSRF\n * vector to close here; the scheme bound is what keeps a credential the\n * deployment set in `headers` from being handed to a scheme that is not HTTP\n * at all. A `file:` or `javascript:` url is a config bug, and it fails the\n * composition the way an impossible policy rule does. The error names no\n * url: the value can carry basic-auth credentials, and an error is logged.\n */\nconst webhookUrl = (raw: string): Effect.Effect<string, AlertError> =>\n  Effect.suspend(() => {\n    const misconfigured = new AlertError({\n      code: \"sink_misconfigured\",\n      message: \"Alert webhook url must be an absolute http: or https: URL\"\n    })\n    let parsed: URL\n    try {\n      parsed = new URL(raw)\n    } catch {\n      return Effect.fail(misconfigured)\n    }\n    return parsed.protocol === \"http:\" || parsed.protocol === \"https:\"\n      ? Effect.succeed(raw)\n      : Effect.fail(misconfigured)\n  })\n\n/**\n * Runs a webhook request with redirect following switched off at the fetch\n * transport.\n *\n * The request carries whatever credential the deployment put in `headers`,\n * and a transport that follows a 3xx re-sends those headers to an origin the\n * deployment never named. Every other fetch default the composition set is\n * kept; only the redirect mode is forced. A 3xx therefore surfaces to the\n * status rule, which calls it `sink_rejected`: a redirecting pager endpoint\n * is a misconfiguration to fix, not an address to forward credentials to.\n */\nconst followingNoRedirects = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>\n  Effect.flatMap(\n    Effect.serviceOption(FetchHttpClient.RequestInit),\n    (init) =>\n      Effect.provideService(effect, FetchHttpClient.RequestInit, {\n        ...(Option.isSome(init) ? init.value : {}),\n        redirect: \"manual\"\n      })\n  )\n\nconst rejected = (status: number): AlertError =>\n  new AlertError({ code: \"sink_rejected\", status, message: `Alert webhook answered ${status}` })\n\n/**\n * The span attributes of a delivery that say nothing of the url's path, query\n * or userinfo: the method, the origin and the answer.\n */\nconst originAttributes: ReadonlySet<string> = new Set([\n  \"http.request.method\",\n  \"url.scheme\",\n  \"server.address\",\n  \"server.port\",\n  \"http.response.status_code\",\n  \"error.type\"\n])\n\nconst isHeaderAttribute = (key: string): boolean =>\n  key.startsWith(\"http.request.header.\") || key.startsWith(\"http.response.header.\")\n\n/**\n * The headers of a redirect that name where the endpoint moved, which is the\n * same secret under another address.\n */\nconst redirectHeaderNames: ReadonlyArray<string> = [\"location\", \"content-location\"]\n\n/**\n * The tracer a delivery opens its HTTP span on: the caller's own, with nothing\n * of the request left on the span.\n *\n * A webhook url is a credential. Slack, Discord and PagerDuty put the secret\n * in the path, others take it in the query, and a url may carry basic-auth\n * userinfo. The HTTP client writes the whole url on its span and again in the\n * failure it ends the span with, and the answer or the transport error it ends\n * with holds the request. So only the attributes that name the method, the\n * origin and the answer are kept, with the headers a host chose to record, and\n * the span ends with the outcome alone: nothing on success, the refusing\n * status, or that the endpoint could not be reached.\n */\nconst withoutRequest = (tracer: Tracer.Tracer): Tracer.Tracer =>\n  Tracer.make({\n    ...tracer,\n    span(options) {\n      const span = tracer.span(options)\n      const end = span.end.bind(span)\n      const attribute = span.attribute.bind(span)\n      span.attribute = (key, value) => {\n        if (originAttributes.has(key) || isHeaderAttribute(key)) attribute(key, value)\n      }\n      span.end = (endTime, exit) => {\n        if (exit._tag === \"Success\") return end(endTime, Exit.void)\n        if (Cause.hasInterruptsOnly(exit.cause)) return end(endTime, exit)\n        const status = span.attributes.get(\"http.response.status_code\")\n        return end(\n          endTime,\n          Exit.fail(\n            typeof status === \"number\"\n              ? rejected(status)\n              : new AlertError({ code: \"sink_unreachable\", message: \"Alert webhook could not be reached\" })\n          )\n        )\n      }\n      return span\n    }\n  })\n\n/**\n * A sink that POSTs each alert to one webhook.\n *\n * The body is the alert plus its {@link alertId}, and the same id is sent as\n * an `Idempotency-Key` header, because the package requires the receiver to\n * dedupe on it and a body without it cannot. The header is set after the\n * caller's headers, so it is the one this sink sends.\n *\n * The endpoint must be an absolute `http:` or `https:` URL, checked when the\n * layer is built, and the request is made with redirect following disabled:\n * the caller's headers can carry a credential, and a followed redirect would\n * re-send them to an origin the deployment never named. A 3xx answer is a\n * refusal like any other non-2xx, not a forwarding instruction. The sink owns\n * its Fetch transport; an externally supplied `HttpClient` is not used.\n * Each delivery has its own scope, which aborts the request and releases any\n * unread response body on completion, failure, timeout, or interruption.\n *\n * The url is treated as a credential, because a webhook's secret usually is\n * its path or query. The delivery's HTTP span is named for the method and\n * records the scheme, host, port and answering status, never the path, the\n * query or userinfo, and it fails with the same url-free reason the sink\n * returns. A host that records HTTP headers on spans gets every name in\n * `headers`, and a redirect's `location`, as `<redacted>`.\n *\n * A non-2xx response is a failure, not a delivery, and an endpoint that never\n * answers is a failure after `timeout`. Paging is exactly the case where a\n * silently dropped request is worse than a retry, and a hung request is worse\n * than either: it is indistinguishable from silence, so it must not be\n * possible to wait on one forever.\n *\n * @param options the endpoint, any headers it needs, and how long to wait\n * @category layers\n * @since 0.1.0\n */\nexport const layerWebhook = (\n  options: {\n    readonly url: string\n    readonly headers?: Readonly<Record<string, string>> | undefined\n    readonly timeout?: Duration.Duration | undefined\n  }\n): Layer.Layer<Sink> =>\n  Layer.effect(\n    Sink,\n    Effect.gen(function*() {\n      const url = yield* Effect.orDie(webhookUrl(options.url))\n      const client = HttpClient.withScope(yield* HttpClient.HttpClient)\n      const timeout = options.timeout ?? defaultWebhookTimeout\n      // `Headers.isRedactedName` compares a string matcher against an\n      // already-lowercased header name without lowercasing the matcher.\n      const redactedNames = [\n        ...Object.keys(options.headers ?? {}).map((name) => name.toLowerCase()),\n        ...redirectHeaderNames\n      ]\n      return {\n        deliver: (alert) =>\n          client.execute(\n            HttpClientRequest.post(url).pipe(\n              (request) =>\n                options.headers === undefined ? request : HttpClientRequest.setHeaders(request, options.headers),\n              HttpClientRequest.setHeader(\"Idempotency-Key\", alertId(alert)),\n              HttpClientRequest.bodyJsonUnsafe({ ...alert, alertId: alertId(alert) })\n            )\n          ).pipe(\n            followingNoRedirects,\n            Effect.updateService(Headers.CurrentRedactedNames, (names) => [...names, ...redactedNames]),\n            // A host may name HTTP spans for their url. This one is named for\n            // its method, as the client names it by default.\n            Effect.provideService(HttpClient.SpanNameGenerator, (request) => request.method),\n            Effect.updateService(Tracer.Tracer, withoutRequest),\n            Effect.flatMap((response) =>\n              response.status >= 200 && response.status < 300\n                ? Effect.void\n                : Effect.fail(rejected(response.status))\n            ),\n            Effect.timeout(timeout),\n            Effect.scoped,\n            Effect.catchTag(\"TimeoutError\", () =>\n              Effect.fail(\n                new AlertError({\n                  code: \"sink_timeout\",\n                  message: `Alert webhook did not answer within ${Duration.toMillis(timeout)} ms`\n                })\n              )),\n            // The transport error holds the request, and the request holds the\n            // caller's headers. Only its reason tag crosses into the failure.\n            Effect.catchTag(\"HttpClientError\", (cause) =>\n              Effect.fail(\n                new AlertError({\n                  code: \"sink_unreachable\",\n                  reason: cause.reason._tag,\n                  message: \"Alert webhook could not be reached\"\n                })\n              ))\n          )\n      }\n    })\n  ).pipe(Layer.provide(FetchHttpClient.layer))\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/AlertPolicy.d.ts

@@ -0,0 +1,284 @@
+/**
+ * Alert policy: what a condition is, when a journal leaves one open, and
+ * which open conditions have outlived their delay.
+ *
+ * Everything here is pure and a function of journal time, so the same entries
+ * decide the same alerts in any process at any instant past the delay. The
+ * transport that pages about them is `./layerWebhook.ts` and the journal-backed
+ * tick that drives them is `./AlertRuntime.ts`; `./Alerts.ts` is the module a
+ * consumer imports.
+ *
+ * @since 1.0.0
+ */
+import type { JournalEvent } from "@smthrs/journal";
+import { Schema } from "effect";
+/**
+ * The journal event type one delivered alert is recorded under.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const deliveredEventType = "flows.alerts.delivered";
+/**
+ * The journal event type one failed delivery attempt is recorded under.
+ *
+ * One entry is written per alert per failure code, never one per tick: a
+ * webhook that stays down for an hour leaves one record, not a hundred and
+ * twenty that every later tick has to read past.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const failedEventType = "flows.alerts.failed";
+/**
+ * How loud an alert is.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const Severity: Schema.Literals<readonly ["info", "warning", "critical"]>;
+/**
+ * How loud an alert is.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Severity = typeof Severity.Type;
+/**
+ * How a condition is recognized in the journal.
+ *
+ * `field` names a payload key, `value` the value that means the condition
+ * holds, and `eventTypes` narrows which entries are consulted at all. An
+ * `eventTypes` item ending in `.*` names a family: `control.*` consults
+ * `control.run.parked` and `control.monitor.beat` alike. An entry that carries
+ * the field with a different value CLOSES the condition, which is what makes a
+ * resume clear an approval alert without a second vocabulary for "cleared".
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const Detector: Schema.Struct<{
+    readonly field: Schema.NonEmptyString;
+    readonly value: Schema.NonEmptyString;
+    readonly eventTypes: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+}>;
+/**
+ * How a condition is recognized in the journal.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Detector = typeof Detector.Type;
+/**
+ * What to do about one condition, and after how long.
+ *
+ * `afterMs` is a whole, non-negative number of milliseconds. The bound is the
+ * schema's job because the delay is also arithmetic on journal time: a `NaN`
+ * delay fires on the first tick and stamps a `firedAt` that JSON writes as
+ * `null`, and a negative one fires with a `firedAt` earlier than the condition
+ * it describes.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const Rule: Schema.Struct<{
+    readonly afterMs: Schema.Int;
+    readonly severity: Schema.optional<Schema.Literals<readonly ["info", "warning", "critical"]>>;
+    readonly owner: Schema.optional<Schema.String>;
+    readonly runbook: Schema.optional<Schema.String>;
+}>;
+/**
+ * What to do about one condition, and after how long.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Rule = typeof Rule.Type;
+/**
+ * The conditions a policy alerts on and the delays it alerts after.
+ *
+ * `defaults` fills in what a rule leaves out, so a policy states the delay per
+ * condition and the ownership once.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const Policy: Schema.Struct<{
+    readonly defaults: Schema.optional<Schema.Struct<{
+        readonly severity: Schema.optional<Schema.Literals<readonly ["info", "warning", "critical"]>>;
+        readonly owner: Schema.optional<Schema.String>;
+        readonly runbook: Schema.optional<Schema.String>;
+    }>>;
+    readonly rules: Schema.$Record<Schema.String, Schema.Struct<{
+        readonly afterMs: Schema.Int;
+        readonly severity: Schema.optional<Schema.Literals<readonly ["info", "warning", "critical"]>>;
+        readonly owner: Schema.optional<Schema.String>;
+        readonly runbook: Schema.optional<Schema.String>;
+    }>>;
+    /** Detectors for conditions this deployment names itself. */
+    readonly detectors: Schema.optional<Schema.$Record<Schema.String, Schema.Struct<{
+        readonly field: Schema.NonEmptyString;
+        readonly value: Schema.NonEmptyString;
+        readonly eventTypes: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+    }>>>;
+}>;
+/**
+ * The conditions a policy alerts on and the delays it alerts after.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Policy = typeof Policy.Type;
+/**
+ * The four conditions a control plane journals out of the box.
+ *
+ * `status` rides on every `control.run.*` entry, and `health` on every
+ * `control.monitor.beat`. A deployment whose supervisor journals a park reason
+ * gets `quota-parked` from the same field the run summary reports it under.
+ *
+ * Each consults the `control.*` family only. A run's journal is shared with
+ * flow steps, agent traces, and anything else that writes to the run, and a
+ * `status` or `health` field on one of those entries would otherwise open or
+ * close a condition the control plane never reported.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export declare const defaultDetectors: Readonly<Record<string, Detector>>;
+/**
+ * A condition that is open on a run, and when it opened.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Open {
+    readonly runId: string;
+    readonly condition: string;
+    /** The journal time of the entry that opened the condition. */
+    readonly since: number;
+}
+/**
+ * One alert a policy decided to raise.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Alert {
+    readonly runId: string;
+    readonly condition: string;
+    readonly since: number;
+    /**
+     * The journal instant the condition outlived its delay: `since` plus the
+     * rule's `afterMs`, never the wall clock of whichever tick noticed.
+     */
+    readonly firedAt: number;
+    readonly severity: Severity;
+    readonly coalescingKey: string;
+    readonly owner?: string | undefined;
+    readonly runbook?: string | undefined;
+}
+/**
+ * The journal source the alerter writes one outcome of one alert under.
+ *
+ * A delivery record counts as evidence that an alert went out only under this
+ * source, so another producer's `flows.alerts.delivered` record with a
+ * matching `alertId` does not suppress a page. This scopes records; it does
+ * not authenticate the writer, because the journal does not bind a source to
+ * a writer.
+ *
+ * @param id the alert's {@link alertId}
+ * @param outcome `delivered`, `refused`, or `failed/<code>`
+ * @private
+ * @since 1.0.0
+ */
+export declare const recordSourceId: (id: string, outcome: string) => string;
+/**
+ * The key an alert coalesces on: one open condition on one run.
+ *
+ * Each component is percent-encoded before it is joined, so a run id or a
+ * condition name containing the separator cannot forge another pair's key and
+ * suppress a page that belongs to somebody else. Both components are values a
+ * deployment chooses, which is why the encoding is not optional.
+ *
+ * @param runId the run the condition is open on
+ * @param condition the condition name the policy uses
+ * @category getters
+ * @since 1.0.0
+ */
+export declare const coalescingKey: (runId: string, condition: string) => string;
+/**
+ * The identity a delivery is recorded under.
+ *
+ * The opening time is part of it on purpose. A condition that clears and
+ * re-opens is a NEW alert, because the second approval wait is not the first
+ * one, and a key without the time would suppress it forever.
+ *
+ * @param alert the alert
+ * @category getters
+ * @since 0.1.0
+ */
+export declare const alertId: (alert: Pick<Alert, "coalescingKey" | "since">) => string;
+/**
+ * The detectors one policy decides with: the four this package ships, with
+ * the deployment's own overriding them by name.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const detectorsOf: (policy: Policy) => Readonly<Record<string, Detector>>;
+/**
+ * One entry's payload when it is a record a detector can read a field off,
+ * and `undefined` for the arrays and primitives that carry no fields at all.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const payloadRecord: (payload: unknown) => Readonly<Record<string, unknown>> | undefined;
+/**
+ * Folds one entry into the open-condition map. Shared by {@link conditions}
+ * and the runtime's incremental read, so both decide a condition the same
+ * way.
+ *
+ * The alerter's own records are never evidence about a condition. They are
+ * written into the same journal they are read from, and they carry the alert's
+ * own vocabulary: a refusal reports the answering HTTP `status`, which a
+ * detector watching the run's `status` would read as the condition clearing.
+ * A page would then close the condition it paged about and the next tick would
+ * re-open it, so a webhook that answered 503 once would alert forever.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const observe: (policy: Policy, detectors: Readonly<Record<string, Detector>>, entry: JournalEvent.Entry, payload: Readonly<Record<string, unknown>>, open: Map<string, number>) => void;
+/**
+ * Every condition a run's journal leaves open, with the time each opened.
+ *
+ * An entry that carries a detector's field opens the condition when the value
+ * matches and closes it when it does not. Entries the detector does not name
+ * are ignored entirely, so a monitor beat cannot close an approval wait and an
+ * approval cannot close a stall.
+ *
+ * @param policy the policy whose detectors decide what counts
+ * @param runId the run the entries belong to
+ * @param entries the run's journal, oldest first
+ * @category projections
+ * @since 0.1.0
+ */
+export declare const conditions: (policy: Policy, runId: string, entries: ReadonlyArray<JournalEvent.Entry>) => ReadonlyArray<Open>;
+/**
+ * The alerts a policy raises for the conditions open at `now`.
+ *
+ * Pure, and a function of journal time: the same journal raises the same
+ * alerts in any process, at any instant past the delay. `now` decides WHETHER
+ * an alert is raised; it never appears in one. A condition that has been open
+ * for less than its rule's delay raises nothing, which is the whole point of
+ * the delay, because most stalls clear themselves.
+ *
+ * @param policy the policy
+ * @param open the conditions the journal left open
+ * @param now the instant to judge them at
+ * @category projections
+ * @since 0.1.0
+ */
+export declare const decide: (policy: Policy, open: ReadonlyArray<Open>, now: number) => ReadonlyArray<Alert>;
+//# sourceMappingURL=AlertPolicy.d.ts.map

package/dist/esm/AlertPolicy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AlertPolicy.d.ts","sourceRoot":"","sources":["../../src/AlertPolicy.ts"],"names":[],"mappings":"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"}