@lantharos/pult 0.11.0 → 0.13.0

package/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { C as traceOrigins, L as findActionDef, M as valuesIn, S as kindOf, _ as normalizeFilter, a as collect, c as guards, d as Transport, h as hasPendingAttachments, i as validate, j as shownValue, k as eachBlock, r as toJsonSchema, x as humanize } from "./schema-DuTVNptF.mjs";
+import { C as traceOrigins, L as findActionDef, M as valuesIn, S as kindOf, _ as normalizeFilter, a as collect, c as guards, d as Transport, h as hasPendingAttachments, i as validate, j as shownValue, k as eachBlock, r as toJsonSchema, x as humanize } from "./schema-DCS7N4sm.mjs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { parseArgs, styleText } from "node:util";
 import { Cron } from "croner";
@@ -184,7 +184,7 @@ function actionChanges(prefix) {
 }
 //#endregion
 //#region package.json
-var version = "0.11.0";
+var version = "0.13.0";
 //#endregion
 //#region ../protocol/src/checks.ts
 const COLUMNS = [
@@ -274,6 +274,7 @@ function checkManifest(manifest) {
 	}
 	for (const [name, page] of Object.entries(manifest.pages)) if (page.blocks) checkBlocks(manifest, page.source, `page ${name}`, page.blocks, problems);
 	if (manifest.status) checkStatus(manifest, problems);
+	for (const [name, rule] of Object.entries(manifest.notify)) checkNotify(manifest, name, rule, problems);
 	for (const [name, flag] of Object.entries(manifest.flags)) {
 		if (flag.target && !manifest.resources[flag.target]) problems.push({
 			source: flag.source,
@@ -390,6 +391,32 @@ function checkSchedule(name, action, problems) {
 		message: `${name} runs on a schedule, so it can't need a second approver`
 	});
 }
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const MIN_ESCALATION_MS = 6e4;
+function checkRecipients(manifest, recipients, problem) {
+	for (const recipient of recipients) {
+		if ("role" in recipient && !manifest.roles[recipient.role]) problem(`role "${recipient.role}", which doesn't exist`);
+		if ("person" in recipient && !EMAIL.test(recipient.person)) problem(`"${recipient.person}", which isn't an email address`);
+	}
+}
+function checkNotify(manifest, name, rule, problems) {
+	const problem = (message) => problems.push({
+		source: rule.source,
+		message: `${name} ${message}`
+	});
+	if (!rule.on.length) problem("doesn't say when to notify");
+	if (!rule.to.length) problem("doesn't say who to notify");
+	for (const inbox of rule.inboxes) if (!manifest.inboxes[inbox]) problem(`watches unknown inbox "${inbox}"`);
+	checkRecipients(manifest, rule.to, (message) => problem(`notifies ${message}`));
+	let previous = 0;
+	for (const step of rule.escalate) {
+		if (step.after < MIN_ESCALATION_MS) problem("escalates sooner than a minute. Use 1m or more.");
+		else if (step.after <= previous) problem("escalates out of order. Each step should come later than the one before.");
+		if (!step.to.length) problem("has an escalation step that doesn't say who to notify");
+		checkRecipients(manifest, step.to, (message) => problem(`escalates to ${message}`));
+		previous = step.after;
+	}
+}
 const COMPONENT = /^[a-z0-9][a-z0-9-]*$/;
 const WEB_ADDRESS = /^https?:\/\/[^\s/$.?#].\S*$/;
 const CSS_LIMIT = 5e4;
@@ -406,7 +433,7 @@ function checkStatus(manifest, problems) {
 		if (component.monitored && component.check) problem(`component ${name} can follow your app or a check, not both`);
 		if (component.check && !WEB_ADDRESS.test(component.check)) problem(`component ${name} checks "${component.check}", which isn't a web address`);
 	}
-	for (const recipient of status.alert) if ("role" in recipient && !manifest.roles[recipient.role]) problem(`alerts role "${recipient.role}", which doesn't exist`);
+	checkRecipients(manifest, status.alert, (message) => problem(`alerts ${message}`));
 	if (status.after < 6e4) problem("waits less than a minute before calling your app down. Use 1m or more.");
 	for (const [what, url] of [
 		["logo", status.logo?.light],
@@ -726,15 +753,32 @@ function byDefinition(a, b) {
 	return a.origin.file.localeCompare(b.origin.file) || a.origin.line - b.origin.line;
 }
 function notifyDef(locator, rule) {
+	const { options } = rule;
 	return {
 		source: locator.call("notify", rule.origin, rule.name),
-		inboxes: rule.options.inboxes.map((inbox) => inbox.name),
-		on: rule.options.on,
-		to: recipients(rule.options.to)
+		inboxes: options.inboxes.map((inbox) => inbox.name),
+		on: options.on,
+		where: options.where ? whereDef(options.where) : null,
+		to: recipients(options.to),
+		escalate: (options.escalate ?? []).map((step) => ({
+			after: milliseconds(step.after),
+			to: recipients(step.to)
+		}))
+	};
+}
+function whereDef(where) {
+	return {
+		tags: where.tags ?? [],
+		data: Object.fromEntries(Object.entries(where.data ?? {}).map(([field, value]) => [field, Array.isArray(value) ? value : [value]]))
 	};
 }
 function recipients(list) {
-	return list.map((recipient) => "channel" in recipient ? { channel: recipient.channel } : { role: recipient.name });
+	return list.map((recipient) => {
+		if ("channel" in recipient) return { channel: recipient.channel };
+		if ("person" in recipient) return { person: recipient.person };
+		if ("assignee" in recipient) return { assignee: true };
+		return { role: recipient.name };
+	});
 }
 function logo(value) {
 	if (value === void 0) return null;

package/index.d.mts

@@ -92,6 +92,7 @@ interface ItemSummary {
   triage: "pending" | "done" | null;
   autoHandled: boolean;
   dueAt: number | null;
+  urgent: boolean;
   fields: Record<string, FieldValue>;
 }
 //#endregion
@@ -102,6 +103,8 @@ type FieldValue = string | number | boolean | null | {
   record: RecordRef;
 } | {
   code: string;
+} | {
+  link: Link;
 } | {
   live: LiveStat;
 } | {
@@ -115,6 +118,10 @@ interface Editable {
   record: string | null;
   field: string | null;
 }
+interface Link {
+  url: string;
+  title?: string;
+}
 interface Sensitive {
   value?: string;
   hint?: string;
@@ -184,6 +191,7 @@ type Block = {
   }[];
 } | {
   type: "table";
+  title?: string;
   columns: string[];
   rows: FieldValue[][];
 } | {
@@ -396,19 +404,34 @@ interface FlagGuard {
   perHour: number;
   then: "pause" | "revert";
 }
-type NotifyTrigger = "created" | "reopened" | "overdue" | {
+type NotifyTrigger = "created" | "reopened" | "overdue" | "urgent" | {
   spike: number;
 };
-type Recipient = {
+type Recipient$1 = {
   role: string;
 } | {
   channel: string;
+} | {
+  person: string;
+} | {
+  assignee: true;
 };
+type MatchValue = string | number | boolean;
+interface NotifyWhere$1 {
+  tags: string[];
+  data: Record<string, MatchValue[]>;
+}
+interface Escalation {
+  after: number;
+  to: Recipient$1[];
+}
 interface NotifyDef {
   source: string;
   inboxes: string[];
   on: NotifyTrigger[];
-  to: Recipient[];
+  where: NotifyWhere$1 | null;
+  to: Recipient$1[];
+  escalate: Escalation[];
 }
 interface StatusComponentDef {
   label: string;
@@ -427,7 +450,7 @@ interface StatusDef<Component extends string = string> {
   website: string | null;
   css: string | null;
   components: Record<Component, StatusComponentDef>;
-  alert: Recipient[];
+  alert: Recipient$1[];
   after: number;
 }
 type Delivery = {
@@ -796,7 +819,11 @@ export declare const b: {
     at: Date | number;
     text: string;
   }[]) => Block;
-  table: (rows: Record<string, FieldInput>[], columns?: string[]) => Block;
+  link: (url: string, title?: string) => FieldValue;
+  table: (rows: Record<string, FieldInput>[], { title, columns }?: {
+    title?: string;
+    columns?: string[];
+  }) => Block;
   stats: (stats: Record<string, FieldInput | {
     value: FieldInput;
     note?: string;
@@ -891,11 +918,30 @@ export declare function space(name: string, options: SpaceOptions): Space;
 interface Channel {
   readonly channel: string;
 }
+interface Person {
+  readonly person: string;
+}
+interface Assignee {
+  readonly assignee: true;
+}
+type Recipient = Role | Channel | Person | Assignee;
 export declare function slack(channel: string): Channel;
+export declare function person(email: string): Person;
+export declare const assignee: Assignee;
+interface NotifyWhere {
+  tags?: string[];
+  data?: Record<string, MatchValue | MatchValue[]>;
+}
+interface EscalationStep {
+  after: Duration;
+  to: Recipient[];
+}
 interface NotifyOptions {
   inboxes: Inbox[];
   on: NotifyTrigger[];
-  to: (Role | Channel)[];
+  where?: NotifyWhere;
+  to: Recipient[];
+  escalate?: EscalationStep[];
 }
 interface Notify extends Located {
   readonly name: string;
@@ -919,7 +965,7 @@ interface StatusOptions {
   website?: string;
   css?: string;
   components: Record<string, string | StatusComponent>;
-  alert?: (Role | Channel)[];
+  alert?: (Role | Channel | Person)[];
   after?: Duration;
 }
 interface Status extends Located {
@@ -965,6 +1011,8 @@ interface SendOptions<S extends Schema | undefined, Suggested extends unknown[]
   data: InboxInput<S>;
   tags?: string[];
   suggest?: { [K in keyof Suggested]: Suggestion<Suggested[K]>; };
+  urgent?: boolean;
+  assign?: string;
 }
 interface ReceivedMessage extends Omit<IncomingMessage, "attachments"> {
   attachments?: BlockInput[];
@@ -995,4 +1043,4 @@ export declare function createPult<Component extends string = string>({ key, pro
 };
 type Pult = ReturnType<typeof createPult>;
 //#endregion
-export type { Action, ActionContext, ActionOptions, ActionRef, Actor, Block, BlockInput, ButtonInput, Channel, ComponentState, Config, ConfigOptions, Duration, FieldInput, Flag, FlagContext, FlagOptions, Guard, Inbox, InboxOptions, ItemView, ListOptions, ListQuery, ListenOptions, Manifest, Notify, NotifyOptions, OutgoingEmail, Page, PageContext, PageOptions, Project, Pult, PultOptions, Question, ReceivedMessage, Relation, Resource, ResourceOptions, Role, RoleOptions, Rule, SendOptions, SendResult, Space, SpaceOptions, StandaloneOptions, StateChange, Status, StatusOptions, Suggestion, Triage, View, ViewOptions };
+export type { Action, ActionContext, ActionOptions, ActionRef, Actor, Assignee, Block, BlockInput, ButtonInput, Channel, ComponentState, Config, ConfigOptions, Duration, EscalationStep, FieldInput, Flag, FlagContext, FlagOptions, Guard, Inbox, InboxOptions, ItemView, ListOptions, ListQuery, ListenOptions, Manifest, Notify, NotifyOptions, NotifyWhere, OutgoingEmail, Page, PageContext, PageOptions, Person, Project, Pult, PultOptions, Question, ReceivedMessage, Recipient, Relation, Resource, ResourceOptions, Role, RoleOptions, Rule, SendOptions, SendResult, Space, SpaceOptions, StandaloneOptions, StateChange, Status, StatusOptions, Suggestion, Triage, View, ViewOptions };

package/index.mjs

@@ -1,4 +1,4 @@
-import { A as mapBlocks, D as sign, E as NonceWindow, F as HOME, I as actionId, L as findActionDef, M as valuesIn, N as DEFAULT_STATES, O as verify, S as kindOf, T as refKey, a as collect, b as captureOrigin, d as Transport, f as b, g as isPendingAttachment, h as hasPendingAttachments, i as validate, k as eachBlock, m as fieldValues, n as reviveDates, o as findAction, p as bindActions, s as flag, t as ValidationError, u as PultError, v as view, w as HEADER, y as KIND } from "./schema-DuTVNptF.mjs";
+import { A as mapBlocks, D as sign, E as NonceWindow, F as HOME, I as actionId, L as findActionDef, M as valuesIn, N as DEFAULT_STATES, O as verify, S as kindOf, T as refKey, a as collect, b as captureOrigin, d as Transport, f as b, g as isPendingAttachment, h as hasPendingAttachments, i as validate, k as eachBlock, m as fieldValues, n as reviveDates, o as findAction, p as bindActions, s as flag, t as ValidationError, u as PultError, v as view, w as HEADER, y as KIND } from "./schema-DCS7N4sm.mjs";
 //#region ../protocol/src/flags.ts
 function rampAt(ramp, now = Date.now()) {
 	if (now >= ramp.end) return ramp.to;
@@ -843,6 +843,8 @@ function createPult({ key = env("PULT_KEY"), project, url = env("PULT_URL") ?? "
 			inbox: inbox.name,
 			fingerprint: item.fingerprint,
 			tags: item.tags,
+			urgent: item.urgent,
+			assign: item.assign,
 			suggest: item.suggest?.map(({ action, ...rest }) => ({
 				action: action.id,
 				...rest
@@ -1039,6 +1041,10 @@ function status(options) {
 function slack(channel) {
 	return { channel: channel.replace(/^#/, "") };
 }
+function person(email) {
+	return { person: email.trim().toLowerCase() };
+}
+const assignee = { assignee: true };
 function notify(name, options) {
 	return {
 		[KIND]: "notify",
@@ -1048,4 +1054,4 @@ function notify(name, options) {
 	};
 }
 //#endregion
-export { PultError, ValidationError, action, b, choice, createPult, defineConfig, flag, home, inbox, notify, noul, page, resource, role, run, score, setState, slack, space, status, tag, triage, view };
+export { PultError, ValidationError, action, assignee, b, choice, createPult, defineConfig, flag, home, inbox, notify, noul, page, person, resource, role, run, score, setState, slack, space, status, tag, triage, view };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lantharos/pult",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "The other side of your app",
   "license": "MIT",
   "keywords": [

package/{schema-DuTVNptF.mjs → schema-DCS7N4sm.mjs}

@@ -361,8 +361,13 @@ const b = {
 			text
 		}))
 	}),
-	table: (rows, columns = Object.keys(rows[0] ?? {})) => ({
+	link: (url, title) => ({ link: {
+		url,
+		...title ? { title } : {}
+	} }),
+	table: (rows, { title, columns = Object.keys(rows[0] ?? {}) } = {}) => ({
 		type: "table",
+		...title ? { title } : {},
 		columns,
 		rows: rows.map((row) => columns.map((column) => field(row[column])))
 	}),
@@ -585,6 +590,7 @@ function collect(modules) {
 				claim(found.notify, rule, "notifications");
 				for (const inbox of rule.options.inboxes) add(inbox);
 				for (const recipient of rule.options.to) add(recipient);
+				for (const step of rule.options.escalate ?? []) for (const recipient of step.to) add(recipient);
 				return;
 			}
 			case "status": {